content/versions/1.15.1/guides/dg/dg.html (5,751 lines of code) (raw):
<!doctype html>
<html>
<head>
<!--
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.
-->
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- No caching headers -->
<meta http-equiv="cache-control" content="no-cache">
<meta http-equiv="pragma" content="no-cache">
<meta http-equiv="expires" content="-1">
<title>Developers' Guide</title>
<link rel="icon" type="image/png" href="../../images/isis-favicon.png">
<!--
Based on DataNucleus' template,
that was in turn based on an earlier version of Apache Isis' template,
that was in turn based on Apache Deltaspike's template.
This template uses
* Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
* Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/)
for the table of contents.
* jQuery (necessary for Bootstrap's JavaScript plugins)
* Font-Awesome for some icons used by Asciidoctor
Also:
* Bootswatch "flatly" theme for Bootstrap (https://bootswatch.com/flatly).
* slick.js (carousel)
* add a link to all headers (home-grown, adapted from blog posts)
* integration of elasticlunr.js (home-grown, adapted from blog posts)
-->
<link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css" rel="stylesheet">
<link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet">
<link href="../../css/asciidoctor/foundation.css" rel="stylesheet">
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
<link href="../../css/slick/1.5.0/slick.css" rel="stylesheet">
<link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet">
<link href="../../css/search-panel/search-panel.css" rel="stylesheet">
<link href="../../css/header-links/header-links.css" rel="stylesheet">
<link href="../../css/sticky-header/sticky-header.css" rel="stylesheet">
<link href="../../css/customisations.css" rel="stylesheet">
<!-- Coderay syntax formatter -->
<style type="text/css">
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
table.CodeRay td{vertical-align: top;line-height:1.45}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
table.CodeRay td.code{padding:0 0 0 .5em}
table.CodeRay td.code>pre{padding:0}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body data-spy="scroll" data-target="#toc">
<div id="basedir" style="display:none;">
../../
</div>
<div id="docname" style="display:none;">
dg
</div>
<div id="filetype" style="display:none;">
html
</div>
<!-- Navbar -->
<nav class="navbar navbar-default navbar-static-top header">
<div class="container">
<div class="navbar-header">
<!-- Three line menu button for use on mobile screens -->
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button>
<a class="navbar-brand" href="../../index.html"> <img alt="Brand" src="../../images/isis-logo-48x48.png"> </a>
<a class="navbar-brand" href="../../index.html">Apache Isis</a>
</div>
<!-- Navbar that will collapse on mobile screens -->
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="../../documentation.html">Table of Contents</a></li>
<li role="separator" class="divider"></li>
<li class="dropdown-header">User Guides</li>
<li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li>
<li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li>
<li><a href="../../guides/ugvro/ugvro.html">Restful Objects Viewer</a></li>
<li><a href="../../guides/ugsec/ugsec.html">Security</a></li>
<li><a href="../../guides/ugtst/ugtst.html">Testing</a></li>
<li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li>
<li role="separator" class="divider"></li>
<li class="dropdown-header">Reference Guides</li>
<li><a href="../../guides/rgant/rgant.html">Annotations</a></li>
<li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li>
<li><a href="../../guides/rgcfg/rgcfg.html">Core Config' Properties</a></li>
<li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and Schema</a></li>
<li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li>
<li><a href="../../guides/rgfis/rgfis.html">Framework Internal Services</a></li>
<li role="separator" class="divider"></li>
<li class="dropdown-header">Javadoc</li>
<li><a href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib">Applib</a></li>
</ul> </li>
<li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Downloads<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="../../downloads.html">Downloads</a></li>
<li><a href="../../release-notes/release-notes.html">Release Notes</a></li>
<li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li>
<li role="separator" class="divider"></li>
<li class="dropdown-header">Maven archetypes</li>
<li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li>
<li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li>
<li role="separator" class="divider"></li>
<li><a href="https://issues.apache.org/jira/browse/ISIS">ASF JIRA</a></li>
<li><a href="https://github.com/apache/isis">Github mirror</a></li>
</ul> </li>
<li class="dropdown hidden-sm"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Support<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="../../support.html">Mailing lists</a></li>
<li><a href="https://lists.apache.org/list.html?users@isis.apache.org">Archives (ASF Pony mail)</a></li>
<li><a href="http://isis.markmail.org/search/?q=">Archives (Markmail)</a></li>
<li><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
<li><a href="../../guides/dg/dg.html">How to contribute</a></li>
<li><a href="../../help.html">Other resources</a></li>
</ul> </li>
<li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="http://www.apache.org/">Apache Homepage</a></li>
<li><a href="http://www.apache.org/licenses/">Licenses</a></li>
<li><a href="http://www.apache.org/security/">Security</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
<li role="separator" class="divider"></li>
<li><a href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a></li>
</ul> </li>
</ul>
<div class="nav navbar-nav navbar-right">
<!-- 'style' added to fix height of input box. FIX THIS -->
<form class="navbar-form" role="search" id="search-form" style="padding: 1px 15px;">
<div class="form-group">
<input class="form-control" id="search-field" type="text" size="30" placeholder="Search">
</div>
</form>
</div>
</div>
</div>
</nav>
<div class="container">
<div class="row-fluid">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-9">
<div id="search-panel">
<div id="search-results"></div>
<div>
<br>
<a href="#" id="search-results-clear">clear</a>
</div>
</div>
<span class="pdf-link"><a href="dg.pdf"><img src="../../images/PDF-50.png"></a></span>
<div class="page-title">
<h1>Developers' Guide</h1>
</div>
<div id="doc-content">
<div class="btn-group" style="float: right; font-size: small; padding: 6px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<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/ugfun.html">Fundamentals</a></p> </li>
<li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li>
<li> <p><a href="../ugvro/ugvro.html">Restful Objects viewer</a></p> </li>
<li> <p><a href="../ugodn/ugodn.html">DataNucleus object store</a></p> </li>
<li> <p><a href="../ugsec/ugsec.html">Security</a></p> </li>
<li> <p><a href="../ugtst/ugtst.html">Testing</a></p> </li>
<li> <p><a href="../ugbtb/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/rgant.html">Annotations</a></p> </li>
<li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li>
<li> <p><a href="../rgcfg/rgcfg.html">Configuration Properties</a></p> </li>
<li> <p><a href="../rgcms/rgcms.html">Classes, Methods and Schema</a></p> </li>
<li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven plugin</a></p> </li>
<li> <p><a href="../rgfis/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="../dg/dg.html">Developers' Guide</a> (this guide)</p> </li>
<li> <p><a href="../cgcom/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="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<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 likewise 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="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</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>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">
<a class="image" href="images/intellij-idea/010-installing/010-welcome-page.png"><img src="images/intellij-idea/010-installing/010-welcome-page.png" alt="010 welcome page" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/010-installing/020-choose-location.png"><img src="images/intellij-idea/010-installing/020-choose-location.png" alt="020 choose location" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/010-installing/030-installation-options.png"><img src="images/intellij-idea/010-installing/030-installation-options.png" alt="030 installation options" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/010-installing/040-start-menu-folder.png"><img src="images/intellij-idea/010-installing/040-start-menu-folder.png" alt="040 start menu folder" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/010-installing/050-completing.png"><img src="images/intellij-idea/010-installing/050-completing.png" alt="050 completing" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/010-installing/060-import-settings-or-not.png"><img src="images/intellij-idea/010-installing/060-import-settings-or-not.png" alt="060 import settings or not" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/010-installing/070-set-ui-theme.png"><img src="images/intellij-idea/010-installing/070-set-ui-theme.png" alt="070 set ui theme" width="600px"></a>
</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">
<a class="image" href="images/intellij-idea/020-create-new-project/010-new-project-create.png"><img src="images/intellij-idea/020-create-new-project/010-new-project-create.png" alt="010 new project create" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png"><img src="images/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png" alt="020 java project setup jdk" width="500px"></a>
</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">
<a class="image" href="images/intellij-idea/020-create-new-project/030-java-project-select-jdk.png"><img src="images/intellij-idea/020-create-new-project/030-java-project-select-jdk.png" alt="030 java project select jdk" width="250px"></a>
</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">
<a class="image" href="images/intellij-idea/020-create-new-project/050-name-and-location.png"><img src="images/intellij-idea/020-create-new-project/050-name-and-location.png" alt="050 name and location" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/020-create-new-project/060-create-dir.png"><img src="images/intellij-idea/020-create-new-project/060-create-dir.png" alt="060 create dir" width="250px"></a>
</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">
<a class="image" href="images/intellij-idea/030-import-settings/040-file-templates.png"><img src="images/intellij-idea/030-import-settings/040-file-templates.png" alt="040 file templates" width="400px"></a>
</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/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">
<a class="image" href="images/intellij-idea/030-import-settings/010-settings-import-jar.png"><img src="images/intellij-idea/030-import-settings/010-settings-import-jar.png" alt="010 settings import jar" width="400px"></a>
</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>If importing into IntelliJ 2017.2.3 two categories are shown - "File templates" and "File templates (schemes)". Select all the categories.</p>
</div>
<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>
</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">
<a class="image" href="images/intellij-idea/030-import-settings/050-live-templates.png"><img src="images/intellij-idea/030-import-settings/050-live-templates.png" alt="050 live templates" width="600px"></a>
</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/dg.html#_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/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/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">
<a class="image" href="images/intellij-idea/040-other-settings-compiler/010-build-automatically.png"><img src="images/intellij-idea/040-other-settings-compiler/010-build-automatically.png" alt="010 build automatically" width="700px"></a>
</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">
<a class="image" href="images/intellij-idea/040-other-settings-compiler/020-annotation-processor.png"><img src="images/intellij-idea/040-other-settings-compiler/020-annotation-processor.png" alt="020 annotation processor" width="700px"></a>
</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="../dg/dg.html#_dg_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">
<a class="image" href="images/intellij-idea/042-other-settings-maven/010-maven-installation.png"><img src="images/intellij-idea/042-other-settings-maven/010-maven-installation.png" alt="010 maven installation" width="700px"></a>
</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">
<a class="image" href="images/intellij-idea/042-other-settings-maven/020-maven-configuration.png"><img src="images/intellij-idea/042-other-settings-maven/020-maven-configuration.png" alt="020 maven configuration" width="700px"></a>
</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">
<a class="image" href="images/intellij-idea/044-other-settings-misc/010-auto-import.png"><img src="images/intellij-idea/044-other-settings-misc/010-auto-import.png" alt="010 auto import" width="700px"></a>
</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">
<a class="image" href="images/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png"><img src="images/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png" alt="010 maven modules view" width="730px"></a>
</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">
<a class="image" href="images/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png"><img src="images/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png" alt="020 adding another module" width="400px"></a>
</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">
<a class="image" href="images/intellij-idea/100-maven-module-mgmt/030-other-module-added.png"><img src="images/intellij-idea/100-maven-module-mgmt/030-other-module-added.png" alt="030 other module added" width="730px"></a>
</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 them from 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">
<a class="image" href="images/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png"><img src="images/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png" alt="040 ignoring modules" width="730px"></a>
</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">
<a class="image" href="images/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png"><img src="images/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png" alt="050 ignoring modules 2" width="300px"></a>
</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">
<a class="image" href="images/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png"><img src="images/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png" alt="060 ignored modules" width="730px"></a>
</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">
<a class="image" href="images/intellij-idea/110-running-the-app/010-run-configuration.png"><img src="images/intellij-idea/110-running-the-app/010-run-configuration.png" alt="010 run configuration" width="600px"></a>
</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">
<a class="image" href="images/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png"><img src="images/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png" alt="020 datanucleus enhancer goal" width="400px"></a>
</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’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>
</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">
<a class="image" href="images/intellij-idea/110-running-the-app/030-running-unit-tests.png"><img src="images/intellij-idea/110-running-the-app/030-running-unit-tests.png" alt="030 running unit tests" width="600px"></a>
</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">
<a class="image" href="images/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png"><img src="images/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png" alt="040 running unit tests run configuration" width="600px"></a>
</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">
<a class="image" href="images/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png"><img src="images/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png" alt="050 running integration tests run configuration" width="600px"></a>
</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/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png"><img src="images/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">
<a class="image" href="images/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png"><img src="images/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png" alt="020 some plugins confirmation" width="600px"></a>
</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/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"><img src="images/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/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"><img src="images/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/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"><img src="images/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/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"><img src="images/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/intellij-idea/060-troubleshooting/010-duplicate-classes.png"><img src="images/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="../dg/dg.html#__dg_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/dg.html#__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>
apply <span class="key">plugin</span>: <span class="string"><span class="delimiter">'</span><span class="content">tangram.tools</span><span class="delimiter">'</span></span>
sourceCompatibility = <span class="float">1.8</span>
targetCompatibility = <span class="float">1.8</span>
version = (<span class="keyword">new</span> XmlParser()).parse(<span class="string"><span class="delimiter">'</span><span class="content">pom.xml</span><span class="delimiter">'</span></span>).parent.version.text()
buildscript {
repositories {
maven { url <span class="string"><span class="delimiter">"</span><span class="content">http://oss.jfrog.org/artifactory/oss-snapshot-local</span><span class="delimiter">"</span></span> }
jcenter()
}
dependencies {
classpath <span class="string"><span class="delimiter">'</span><span class="content">tangram:gradle-plugin:1.1.2</span><span class="delimiter">'</span></span>
}
}
repositories {
mavenLocal()
maven { url <span class="string"><span class="delimiter">"</span><span class="content">http://oss.jfrog.org/artifactory/oss-snapshot-local</span><span class="delimiter">"</span></span> }
jcenter()
}
dependencies {
compile <span class="key">group</span>: <span class="string"><span class="delimiter">'</span><span class="content">org.apache.isis.core</span><span class="delimiter">'</span></span>, <span class="key">name</span>: <span class="string"><span class="delimiter">'</span><span class="content">isis-core-applib</span><span class="delimiter">'</span></span>, <span class="key">version</span>: version
}
task copyClasses << {
copy {
from <span class="string"><span class="delimiter">'</span><span class="content">build/classes/main</span><span class="delimiter">'</span></span>
into <span class="string"><span class="delimiter">'</span><span class="content">target/classes</span><span class="delimiter">'</span></span>
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The script is intended to be in the background as a daemon while editing/developing; whenever a change is made to any source code, gradle will automatically compile <em>and</em> enhance the code. In this way it eliminates the need to start up Maven and run the enhancer goal.</p>
</div>
<div class="paragraph">
<p>To use, you must disable the IntelliJ’s automatic building of the 'dom' project. This is done using: <code>File > Settings > Build, Execution, Deployment > Compiler > Excludes</code>, and then exclude the <code>…/dom/src/main/java</code> directory:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/002-compiler-exclude.png"><img src="images/intellij-idea/070-advanced/002-compiler-exclude.png" alt="002 compiler exclude" width="800px"></a>
</div>
</div>
<div class="paragraph">
<p>The script can be run in the background using:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">gradle -t --offline &</code></pre>
</div>
</div>
<div class="paragraph">
<p>from the command line (in the <code>dom</code> module).</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/004-gradle-output.png"><img src="images/intellij-idea/070-advanced/004-gradle-output.png" alt="004 gradle output" width="600px"></a>
</div>
</div>
</div>
<div class="sect4">
<h5 id="__dg_ide_intellij_advanced_gradle-liveReload">Using Gradle for liveReload</h5>
<div class="paragraph">
<p>Similarly, gradle can be run to reduce the turn-around time when tweaking the UI (defined by the <a href="../ugvw/ugvw.html#_ugvw_layout_file-based"><code>*.layout.xml</code></a> file for each domain class), when the app is running.</p>
</div>
<div class="paragraph">
<p>The framework will automatically notice any changes to <code>.layout.xml</code> files, but these are read from the the classpath (the <code>target/classes</code> directory), not the source path. With IntelliJ these can be copied over manually by invoking <code>Run > Reload Changed Classes</code>. Once the browser is refreshed, the new layout will be rendered.</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>We’ve occasionally noticed that this interferes with Wicket’s own javascript - switching tabs becomes unresponsive. The work-around is just to reload the page.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>To reduce the turn-around time there are therefore two steps to be automated:</p>
</div>
<div class="ulist">
<ul>
<li> <p>the copying of the <code>.layout.xml</code> files over to the <code>target/classes</code> directory</p> </li>
<li> <p>the triggering of a page refresh by the browser.</p> </li>
</ul>
</div>
<div class="paragraph">
<p>The <code>layouts.gradle</code> script takes care of the first of these; whenever a change is made to any <code>.layout.xml</code> file, gradle will automatically copy over the file to the <code>target/classes</code> directory:</p>
</div>
<div class="listingblock">
<div class="title">
<code>layouts.gradle</code>
</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">defaultTasks <span class="string"><span class="delimiter">'</span><span class="content">copyLayouts</span><span class="delimiter">'</span></span>
task copyLayouts(<span class="key">type</span>:Copy) {
from <span class="string"><span class="delimiter">'</span><span class="content">src/main/java</span><span class="delimiter">'</span></span>
into <span class="string"><span class="delimiter">'</span><span class="content">target/classes</span><span class="delimiter">'</span></span>
include <span class="string"><span class="delimiter">'</span><span class="content">**/*.layout.xml</span><span class="delimiter">'</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Similarly, the <code>liveReload.gradle</code> script takes care of the browser refresh:</p>
</div>
<div class="listingblock">
<div class="title">
<code>liveReload.gradle</code>
</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">defaultTasks <span class="string"><span class="delimiter">'</span><span class="content">liveReload</span><span class="delimiter">'</span></span>
buildscript {
repositories {
jcenter()
}
dependencies {
classpath <span class="string"><span class="delimiter">'</span><span class="content">org.kordamp.gradle:livereload-gradle-plugin:0.2.1</span><span class="delimiter">'</span></span>
}
}
apply <span class="key">plugin</span>: <span class="string"><span class="delimiter">'</span><span class="content">org.kordamp.gradle.livereload</span><span class="delimiter">'</span></span>
liveReload {
docRoot <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">'</span><span class="content">target/classes</span><span class="delimiter">'</span></span>).canonicalPath
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>These scripts can be run together using:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">gradle -t --offline -b layouts.gradle &
gradle -t --offline -b liveReload.gradle &</code></pre>
</div>
</div>
<div class="paragraph">
<p>from the command line (in the <code>dom</code> module):</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/005-gradle-output.png"><img src="images/intellij-idea/070-advanced/005-gradle-output.png" alt="005 gradle output" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>Live reload also requires that the <code>isis.viewer.wicket.liveReloadUrl</code> configuration property is set appropriately:</p>
</div>
<div class="listingblock">
<div class="title">
<code>viewer_wicket.properties</code>
</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="ini">isis.viewer.wicket.liveReloadUrl=http://localhost:35729/livereload.js?snipver=1</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can confirm the script is loaded correctly using the web browser’s development tools, eg:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/006-livereload-js.png"><img src="images/intellij-idea/070-advanced/006-livereload-js.png" alt="006 livereload js" width="800px"></a>
</div>
</div>
</div>
<div class="sect4">
<h5 id="__dg_ide_intellij_advanced_dcevm">Setting up DCEVM</h5>
<div class="paragraph">
<p><a href="http://github.com/dcevm/dcevm">DCEVM</a> enhances the JVM with true hot-swap adding/removing of methods as well as more reliable hot swapping of the implementation of existing methods.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>To set up DCEVM, download the appropriate JAR from the <a href="https://dcevm.github.io/">github page</a>, and run the installer. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">java -jar DCEVM-light-8u51-installer.jar</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
<p>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 <code>Administrator</code>.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>After a few seconds this will display a dialog listing all installations of JDK that have been found:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png"><img src="images/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png" alt="010 dcevm list of found jdk installations" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>Select the corresponding installation, and select <code>Replace by DCEVM</code>.</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/020-dcevm-once-installed.png"><img src="images/intellij-idea/070-advanced/020-dcevm-once-installed.png" alt="020 dcevm once installed" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>In IntelliJ, register the JDK in <code>File > Project Structure</code> dialog:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png"><img src="images/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png" alt="030 dcevm intellij project structure" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>Finally, in the run configuration, select the patched JDK:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/intellij-idea/070-advanced/040-dcevm-run-configuration.png"><img src="images/intellij-idea/070-advanced/040-dcevm-run-configuration.png" alt="040 dcevm run configuration" width="600px"></a>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_setting_up_jrebel">Setting up JRebel</h5>
<div class="paragraph">
<p>See the repo for the (non-ASF) <a href="https://github.com/isisaddons/isis-jrebel-plugin">Isis JRebel</a> plugin.</p>
</div>
<div class="paragraph">
<p>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).</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_dg_ide_eclipse">2.2. Developing using Eclipse</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</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>This material does not constitute an endorsement; Eclipse foundation is not affiliated to Apache Software Foundation in any way.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>If you are an <a href="http://www.eclipse.org">Eclipse</a> user, then we recommend you download the "Eclipse JEE package" configuration.</p>
</div>
<div class="paragraph">
<p>When running an Apache Isis application, it’s necessary to setup the development environment so that the Java bytecode can be enhanced by the <a href="http://www.datanucleus.org">DataNucleus</a> enhancer. If working in Eclipse, then JDO enhancement is most easily done by installing the <a href="http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html">DataNucleus' Eclipse plugin</a>. This hooks the bytecode enhancement of your domain objects into Eclipse’s normal incremental compilation.</p>
</div>
<div class="paragraph">
<p>This plugin needs to be configured for each of your domain modules (usually just one in any given app). The steps are therefore:</p>
</div>
<div class="ulist">
<ul>
<li> <p>import the project into Eclipse</p> </li>
<li> <p>configure the DataNucleus enhancer</p> </li>
<li> <p>run the app from the <code>.launch</code> file</p> </li>
</ul>
</div>
<div class="sect3">
<h4 id="__dg_ide_eclipse_screencast">2.2.1. Screencast</h4>
<div class="paragraph">
<p>This <a href="https://www.youtube.com/watch?v=RgcYfjQ8yJA">screencast</a> shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore.</p>
</div>
</div>
<div class="sect3">
<h4 id="__dg_ide_eclipse_editor-templates">2.2.2. Editor Templates</h4>
<div class="paragraph">
<p>We provide a set of editor templates. These are used to add new methods to existing classes. (These are equivalent to the <a href="../dg/dg.html#__dg_ide_intellij_live-templates">IntelliJ live templates</a>):</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>is</code> (Apache Isis domain objects). <a href="./resources/eclipse/isis-templates.xml">Download</a></p> </li>
<li> <p><code>ju</code> (for JUnit tests) <a href="./resources/eclipse/junit4-templates.xml">Download</a></p> </li>
<li> <p><code>jm</code> (for JMock mocks or libraries) <a href="./resources/eclipse/jmock2-templates.xml">Download</a></p> </li>
</ul>
</div>
<div class="paragraph">
<p>To install, download each XML file, then go to <code>Windows > Preferences > Java > Editor > Templates</code> and choose <code>Import</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="__dg_ide_eclipse_importing-the-project">2.2.3. Importing the Project</h4>
<div class="paragraph">
<p>Use File > Import, then Maven > Existing Maven Projects.</p>
</div>
</div>
<div class="sect3">
<h4 id="_add_datanucleus_support">2.2.4. Add DataNucleus support</h4>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
<p>Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>In Eclipse, for the <em>domain object model</em> project, first add DataNucleus support:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-100-project-support.png"><img src="images/eclipse/eclipse-100-project-support.png" alt="eclipse 100 project support" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>Then turn on Auto-Enhancement:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-110-project-support.png"><img src="images/eclipse/eclipse-110-project-support.png" alt="eclipse 110 project support" width="600px"></a>
</div>
</div>
<div class="sect4">
<h5 id="_update_the_classpath">Update the classpath</h5>
<div class="paragraph">
<p>DataNucleus' enhancer uses the domain object model’s own classpath to reference DataNucleus JARs. So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.</p>
</div>
<div class="paragraph">
<p>See the section in <a href="#_dg_hints-and-tips_datanucleus-enhancer">DataNucleus enhancer</a> for details of the contents of the <code>pom.xml</code>. Chances are it is already set up from running the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> or the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a> archetype.</p>
</div>
<div class="paragraph">
<p>Then, tell DataNucleus to use the project classpath:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-010-windows-preferences.png"><img src="images/eclipse/eclipse-010-windows-preferences.png" alt="eclipse 010 windows preferences" width="750px"></a>
</div>
</div>
<div class="paragraph">
<p>When the enhancer runs, it will print out to the console:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-120-console.png"><img src="images/eclipse/eclipse-120-console.png" alt="eclipse 120 console" width="500px"></a>
</div>
</div>
</div>
<div class="sect4">
<h5 id="__dg_ide_eclipse_workaround-for-path-limits">Workaround for path limits (the DN plugin to use the persistence.xml)</h5>
<div class="paragraph">
<p>If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.</p>
</div>
<div class="paragraph">
<p>To fix this, we configure the enhancer to read from the <code>persistence.xml</code> file.</p>
</div>
<div class="paragraph">
<p>As a prerequisite, first make sure that your domain object model has a <code>persistence.xml</code> file. Then specify the <code>persistence-unit</code> in the project properties:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-025-project-properties.png"><img src="images/eclipse/eclipse-025-project-properties.png" alt="eclipse 025 project properties" width="750px"></a>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_workaround_if_the_enhancer_fails">Workaround: If the enhancer fails</h5>
<div class="paragraph">
<p>On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we’ve noticed multiple entries in the Eclipse’s <code>Debug</code> view:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-210-enhancer-fails-duplicates.png"><img src="images/eclipse/eclipse-210-enhancer-fails-duplicates.png" alt="eclipse 210 enhancer fails duplicates" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>At any rate, you’ll know you’ve encountered this error if you see the following in the console:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-200-enhancer-fails-duplicates.png"><img src="images/eclipse/eclipse-200-enhancer-fails-duplicates.png" alt="eclipse 200 enhancer fails duplicates" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>The best solution is to remove DataNucleus support and then to re-add it:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/eclipse/eclipse-220-enhancer-fails-duplicates.png"><img src="images/eclipse/eclipse-220-enhancer-fails-duplicates.png" alt="eclipse 220 enhancer fails duplicates" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.</p>
</div>
<div class="paragraph">
<p>Not ideal, we know. Please feel free to contribute a better solution :-)</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_running_the_app">2.2.5. Running the App</h4>
<div class="paragraph">
<p>The simpleapp archetype automatically provides a <code>.launch</code> configurations in the <code>webapp</code> module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".</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>The screencast above shows this in action.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_other_domain_projects">2.2.6. Other domain projects.</h4>
<div class="paragraph">
<p>There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a <a href="http://www.methodsandtools.com/archive/archive.php?id=97p2">DDD module</a>, thus guaranteeing that there are no cyclic dependencies between your modules.</p>
</div>
<div class="paragraph">
<p>If you do this, make sure that each project has its own <code>persistence.xml</code> file.</p>
</div>
<div class="paragraph">
<p>And, remember also to configure Eclipse’s DataNucleus plugin for these other domain projects.</p>
</div>
</div>
<div class="sect3">
<h4 id="_advanced">2.2.7. Advanced</h4>
<div class="paragraph">
<p>In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.</p>
</div>
<div class="sect4">
<h5 id="_setting_up_dcevm">Setting up DCEVM</h5>
<div class="paragraph">
<p><a href="http://github.com/dcevm/dcevm">DCEVM</a> enhances the JVM with true hot-swap adding/removing of methods as well as more reliable hot swapping of the implementation of existing methods.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>For details of setting up DCEVM, see the <a href="../dg/dg.html#__dg_ide_intellij_advanced_dcevm">corresponding section</a> in the IntelliJ documentation.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_hints-and-tips">3. Hints and Tips</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter provides some solutions for problems we’ve encountered ourselves or have been raised on the Apache Isis mailing lists.</p>
</div>
<div class="paragraph">
<p>See also hints-n-tips chapters in the:</p>
</div>
<div class="ulist">
<ul>
<li> <p>the <a href="../dg/dg.html#_dg_hints-and-tips">Developers'</a> guide (this chapter)</p> </li>
<li> <p>the <a href="../ugvw/ugvw.html#_ugvw_hints-and-tips">Wicket viewer</a> guide</p> </li>
<li> <p>the <a href="../ugvro/ugvro.html#_ugvro_hints-and-tips">Restful Objects viewer</a> guide</p> </li>
<li> <p>the <a href="../ugodn/ugodn.html#_ugodn_hints-and-tips">Datanucleus ObjectStore</a> guide</p> </li>
<li> <p>the <a href="../ugsec/ugsec.html#_ugsec_hints-and-tips">Security</a> guide</p> </li>
<li> <p>the <a href="../ugbtb/ugbtb.html#_ugbtb_hints-and-tips">Beyond the Basics</a> guide.</p> </li>
</ul>
</div>
<div class="sect2">
<h3 id="_dg_hints-and-tips_datanucleus-enhancer">3.1. Datanucleus Enhancer</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_datanucleus-enhancer.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p><a href="http://www.datanucleus.org/">DataNucleus</a> is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as <a href="http://neo4j.com/">Neo4J</a>, <a href="http://www.mongodb.org/">MongoDB</a> and <a href="http://cassandra.apache.org/">Apache Cassandra</a>.</p>
</div>
<div class="paragraph">
<p>With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.</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>Bytecode enhancement is actually a requirement of the JDO spec; the process is described in outline <a href="http://db.apache.org/jdo/enhancement.html">here</a>.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>What this means is that the enhancer — available as both a Maven plugin and as an Eclipse plugin — must, one way or another, be integrated into your development environment.</p>
</div>
<div class="paragraph">
<p>If working from the Maven command line, JDO enhancement is done using the <code>maven-datanucleus-plugin</code>.</p>
</div>
<div class="paragraph">
<p>Both the <a href="ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> and <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a> Maven archetypes generate applications that have this plugin pre-configured.</p>
</div>
<div class="sect3">
<h4 id="_meta_inf_persistence_xml">3.1.1. META-INF/persistence.xml</h4>
<div class="paragraph">
<p>It’s also a good idea to ensure that every domain module(s) containing entities has a JDO <code>META-INF/persistence.xml</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF-8" ?></span>
<span class="tag"><persistence</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://java.sun.com/xml/ns/persistence</span><span class="delimiter">"</span></span>
<span class="attribute-name">xmlns:xsi</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema-instance</span><span class="delimiter">"</span></span>
<span class="attribute-name">xsi:schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd</span><span class="delimiter">"</span></span> <span class="attribute-name">version</span>=<span class="string"><span class="delimiter">"</span><span class="content">1.0</span><span class="delimiter">"</span></span><span class="tag">></span>
<span class="tag"><persistence-unit</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">simple</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b>
<span class="tag"></persistence-unit></span>
<span class="tag"></persistence></span></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tbody>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>change as required; typically is the name of the domain module.</td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>Again, the applications generated by both the <a href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a> and <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">Simpleapp</a> Maven archetypes do this.</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>If running on Windows, then there’s a good chance you’ll hit the <a href="http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath">maximum path length limit</a>. In this case the <code>persistence.xml</code> file is mandatory rather than optional.</p>
</div>
<div class="paragraph">
<p>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 <a href="../dg/dg.html#_dg_ide_eclipse">here</a>.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_dg_hints-and-tips_enabling-logging">3.2. Enabling Logging</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>Sometimes you just need to see what is going on. There are various ways in which logging can be enabled, here are the ones we tend to use.</p>
</div>
<div class="ulist">
<ul>
<li> <p>In Apache Isis<br></p>
<div class="paragraph">
<p>Modify <code>WEB-INF/logging.properties</code> (a log4j config file)</p>
</div> </li>
<li> <p>In DataNucleus<br></p>
<div class="paragraph">
<p>As per the <a href="http://www.datanucleus.org/products/accessplatform/logging.html">DN logging page</a></p>
</div> </li>
<li> <p>In the JDBC Driver<br></p>
<div class="paragraph">
<p>Configure <code>log4jdbc</code> JDBC rather than the vanilla driver (see <code>WEB-INF/persistor_datanucleus.properties</code>) and configure log4j logging (see <code>WEB-INF/logging.properties</code>). There are examples of both in the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
</div> </li>
<li> <p>In the database<br></p>
<div class="paragraph">
<p>Details below.</p>
</div> </li>
</ul>
</div>
<div class="paragraph">
<p>Database logging can be configured:</p>
</div>
<div class="ulist">
<ul>
<li> <p>for HSQLDB<br></p>
<div class="paragraph">
<p>by adding`;sqllog=3` to the end of the JDBC URL.</p>
</div> </li>
<li> <p>for PostgreSQL:<br></p>
<div class="paragraph">
<p>Can change <code>postgresql\9.2\data\postgresql.conf</code>; see <a href="http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html">this article</a> for details.</p>
</div> </li>
<li> <p>for MS SQL Server Logging:<br></p>
<div class="paragraph">
<p>We like to use the excellent SQL Profiler tool.</p>
</div> </li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_dg_hints-and-tips_enhance-only">3.3. Enhance only (IntelliJ)</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>From the Apache Isis mailing list is:</p>
</div>
<div class="ulist">
<ul>
<li> <p><em>Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?</em></p> </li>
</ul>
</div>
<div class="paragraph">
<p>Yes, you can; here’s one way:</p>
</div>
<div class="ulist">
<ul>
<li> <p>Duplicate your run configuration for running the webapp</p>
<div class="ulist">
<ul>
<li> <p>the one where the main class is <code>org.apache.isis.WebServer</code></p> </li>
<li> <p>there’s a button for this on the run configurations dialog.</p> </li>
</ul>
</div> </li>
<li> <p>then, on your copy change the main class to <code>org.apache.isis.Dummy</code></p> </li>
</ul>
</div>
<div class="paragraph">
<p>Or, you could just write a small shell script and run from the command line:</p>
</div>
<div class="listingblock">
<div class="title">
enhance.sh
</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">mvn -pl dom datanucleus:enhance -o</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_dg_hints-and-tips_how-run-fixtures-on-app-startup">3.4. How run fixtures on startup?</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>From this <a href="http://isis.markmail.org/thread/g6amfj2eyf2xfjbr">thread</a> on the Apache Isis users mailing list:</p>
</div>
<div class="ulist">
<ul>
<li> <p><em>my fixtures have grown into a couple of files the application needs to read in when it starts the first time (and possibly later on when the files content change). What is the right way to do this? Hook up into the webapp start? Use events?</em></p> </li>
</ul>
</div>
<div class="paragraph">
<p>The standard approach is to use <a href="../ugtst/ugtst.html#_ugtst_fixture-scripts">fixture scripts</a>. These can be run in on start-up typically by being specified in the <a href="../rgcms/rgcms.html#_rgcms_classes_AppManifest-bootstrapping"><code>AppManifest</code></a>, see for example the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
</div>
<div class="paragraph">
<p>Alternatively just set <code>isis.fixtures</code> and <code>isis.persistor.datanucleus.install-fixtures</code> properties.</p>
</div>
<div class="paragraph">
<p>In terms of implementations, you might also want to check out the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s excel module, by using <code>ExcelFixture</code> and overriding <code>ExcelFixtureRowHandler</code>.</p>
</div>
<div class="paragraph">
<p>An example can be found in this (non ASF) <a href="https://github.com/incodehq/contactapp">contactapp</a>, see <a href="https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/org/incode/eurocommercial/contactapp/fixture/scenarios/demo/ContactImport.java"><code>ContactRowHandler</code></a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_building-isis">4. Building Apache Isis</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="sect2">
<h3 id="__dg_building-isis_git">4.1. Git</h3>
<div class="paragraph">
<p>The Apache Isis source code lives in a git repo.</p>
</div>
<div class="sect3">
<h4 id="__dg_building-isis_git_installation">4.1.1. Installation</h4>
<div class="paragraph">
<p>The easiest place to get hold of command-line git is probably the <a href="http://git-scm.com/downloads">github download page</a>.</p>
</div>
<div class="paragraph">
<p>On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/building-isis/setting-up-git.png"><img src="images/building-isis/setting-up-git.png" alt="setting up git" width="350px"></a>
</div>
</div>
<div class="paragraph">
<p>Once git is installed, the two main command line tools to note are:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>git</code> command line tool</p> </li>
<li> <p><code>gitk</code> for viewing the commit history</p> </li>
</ul>
</div>
<div class="paragraph">
<p>If using Windows, note that github also have a dedicated <a href="https://help.github.com/articles/set-up-git">Windows client</a>. With a little <a href="http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx">hacking around</a>, it can also be made to work with non-github repositories.</p>
</div>
<div class="paragraph">
<p>If using Mac, you might also want to check out Atlassian’s <a href="http://www.atlassian.com/software/sourcetree/overview">Sourcetree</a>.</p>
</div>
<div class="sect4">
<h5 id="__dg_building-isis_git_installation_cloning-the-apache-isis-repo">Cloning the Apache Isis repo</h5>
<div class="paragraph">
<p>First, clone the Apache Isis repo.</p>
</div>
<div class="paragraph">
<p>If you are a <strong>committer</strong>, then clone from the Apache read/write repo:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git clone https://git-wip-us.apache.org/repos/asf/isis.git</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you are <strong>not a committer</strong>, please see the <a href="../dg/dg.html#_dg_contributing">contributing</a> page for details on which repo to clone from.</p>
</div>
</div>
<div class="sect4">
<h5 id="__dg_building-isis_git_installation_configuring-git">Configuring Git</h5>
<div class="paragraph">
<p>Next up is to configure your user name and password; see also <a href="https://git-wip-us.apache.org/">Apache’s git</a> docs:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git config user.name "<i>My Name Here</i>"
git config user.email <i>myusername@apache.org</i></code></pre>
</div>
</div>
<div class="paragraph">
<p>Next, configure the <code>core.autocrlf</code> so that line endings are normalized to LF (Unix style) in the rep; again see <a href="https://git-wip-us.apache.org/">Apache’s git</a> page:</p>
</div>
<div class="ulist">
<ul>
<li> <p>on Windows, use:<br></p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git config core.autocrlf true</code></pre>
</div>
</div> </li>
<li> <p>on Mac/Linux, use:<br></p>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git config core.autocrlf input</code></pre>
</div>
</div> </li>
</ul>
</div>
<div class="paragraph">
<p>The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.</p>
</div>
<div class="paragraph">
<p>We also recommend setting <code>core.safecrlf</code>, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git config core.safecrlf true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that these settings are supplemented in the repo by the <code>.gitattributes</code> file and that explicitly specifies line handling treatment for most of the common file types that we have.</p>
</div>
<div class="paragraph">
<p>Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the <code>[remote "origin"]</code> section in your <code>.git/config</code> and add the third entry shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">[remote "origin"]
url = ... whatever ...
fetch = ... whatever ...
fetch = +refs/tags/*:refs/tags/origin/*</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will ensure that a <code>git fetch</code> or <code>git pull</code> places any remote tags under <code>origin/xxx. For example, the`isis-1.0.0`tag on the origin will appear under`origin/isis-1.0.0</code>.</p>
</div>
<div class="paragraph">
<p>If you don’t use git outside of Apache, you can add the <code>--global</code> flag so that the above settings apply for all repos managed by git on your PC.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="__dg_building-isis_git_getting-help">4.1.2. Getting help</h4>
<div class="paragraph">
<p>Three commands of git that in particular worth knowing:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>git help <em>command</em></code><br></p>
<div class="paragraph">
<p>will open the man page in your web browser</p>
</div> </li>
<li> <p><code>git gui</code><br></p>
<div class="paragraph">
<p>will open up a basic GUI client to staging changes and making commits.</p>
</div> </li>
<li> <p><code>gitk --all</code><br></p>
<div class="paragraph">
<p>will open the commit history for all branches. In particular, you should be able to see the local <code>master</code>, which branch you are working on (the <code>HEAD</code>), and also the last known position of the <code>master</code> branch from the central repo, called <code>origin/master</code>.</p>
</div> </li>
</ul>
</div>
<div class="paragraph">
<p>You might also want to explore using a freely available equivalent such as <a href="https://www.sourcetreeapp.com/">Atlassian SourceTree</a>.</p>
</div>
<div class="paragraph">
<p>For further reading, see:</p>
</div>
<div class="ulist">
<ul>
<li> <p><a href="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git config man page</a></p> </li>
<li> <p><a href="http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html">.gitattributes man page</a></p> </li>
<li> <p><a href="http://git-scm.com/docs/gitattributes">.gitattributes git-scm.com docs</a></p> </li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_building-isis_installing-java">4.2. Installing Java</h3>
<div class="paragraph">
<p>Apache Isis is compatible with Java 7 and Java 8. For every-day use, the framework is usually compiled against Java 8.</p>
</div>
<div class="paragraph">
<p>Releases however are <a href="../cgcom/cgcom.html#_cgcom_cutting-a-release">cut</a> using Java 7, leveraging the <a href="http://maven.apache.org/plugins/maven-toolchains-plugin/">Maven toolchains plugin</a>).</p>
</div>
<div class="paragraph">
<p>Therefore install either/both of Java 7 JDK and Java 8 JDK. Note that the JRE is <em>not</em> sufficient.</p>
</div>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
<p>If you intend to contribute back patches to Apache Isis, note that while you can develop using Java 8 within your IDE, be sure not to use any Java 8 APIs.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="__dg_building-isis_configure-maven-toolchains-plugin">4.2.1. Configure Maven toolchains plugin</h4>
<div class="paragraph">
<p>If you are a committer that will be performing releases of Apache Isis, then you <em>must</em> configure the <a href="http://maven.apache.org/plugins/maven-toolchains-plugin/">toolchains</a> plugin so that releases can be built using Java 7.</p>
</div>
<div class="paragraph">
<p>This is done by placing the <code>toolchains.xml</code> file in <code>~/.m2</code> directory. Use the following file as a template, adjusting paths for your platform:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF8"?></span>
<span class="tag"><toolchains></span>
<span class="tag"><toolchain></span>
<span class="tag"><type></span>jdk<span class="tag"></type></span>
<span class="tag"><provides></span>
<span class="tag"><version></span>1.8<span class="tag"></version></span>
<span class="tag"><vendor></span>oracle<span class="tag"></vendor></span>
<span class="tag"></provides></span>
<span class="tag"><configuration></span>
<span class="tag"><jdkHome></span>/usr/lib64/jvm/jdk1.8.0_65<span class="tag"></jdkHome></span>
<span class="comment"><!-- <jdkHome>c:\Program Files\Java\jdk1.8.0_65</jdkHome> --></span>
<span class="tag"></configuration></span>
<span class="tag"></toolchain></span>
<span class="tag"><toolchain></span>
<span class="tag"><type></span>jdk<span class="tag"></type></span>
<span class="tag"><provides></span>
<span class="tag"><version></span>1.7<span class="tag"></version></span> <i class="conum" data-value="1"></i><b>(1)</b>
<span class="tag"><vendor></span>oracle<span class="tag"></vendor></span>
<span class="tag"></provides></span>
<span class="tag"><configuration></span>
<span class="tag"><jdkHome></span>/usr/lib64/jvm/jdk1.7.0_79<span class="tag"></jdkHome></span>
<span class="comment"><!-- <jdkHome>c:\Program Files\Java\jdk1.7.0_79</jdkHome> --></span>
<span class="tag"></configuration></span>
<span class="tag"></toolchain></span>
<span class="tag"></toolchains></span></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tbody>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>The Apache Isis build is configured to search for the (<code>1.7, oracle</code>) JDK toolchain.</td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>The Apache Isis parent <code>pom.xml</code> activates this plugin whenever the <code>apache-release</code> profile is enabled.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_building-isis_installing-maven">4.3. Installing Maven</h3>
<div class="paragraph">
<p>Install Maven 3.0.x, downloadable <a href="http://maven.apache.org/download.html">here</a>.</p>
</div>
<div class="paragraph">
<p>Set <code>MAVEN_OPTS</code> environment variable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">export MAVEN_OPTS="-Xms512m -Xmx1024m"</code></pre>
</div>
</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>Previously we suggested <code>-XX:MaxPermSize=256m</code>, but this option has been removed in Java 8. (As of <code>1.9.0</code>, Apache Isis is built using Java 8 but with source and target set to JDK 1.7).</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="__dg_building-isis_building-all-of-apache-isis">4.4. Building all of Apache Isis</h3>
<div class="paragraph">
<p>To build the source code from the command line, simply go to the root directory and type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">mvn clean install</code></pre>
</div>
</div>
<div class="paragraph">
<p>The first time you do this, you’ll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.</p>
</div>
<div class="paragraph">
<p>Thereafter you can speed up the build by adding the <code>-o</code> (offline flag). To save more time still, we also recommend that you build in parallel. (Per this <a href="http://zeroturnaround.com/rebellabs/your-maven-build-is-slow-speed-it-up/">blog post</a>), you could also experiment with a number of JDK parameters that we’ve found also speed up Maven:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:+TieredCompilation -XX:TieredStopAtLevel=1"
mvn clean install -o -T1C</code></pre>
</div>
</div>
<div class="paragraph">
<p>For the most part, though, you may want to rely on an IDE such as Eclipse to build the codebase for you. Both Eclipse and Idea (12.0+) support incremental background compilation.</p>
</div>
<div class="paragraph">
<p>When using Eclipse, a Maven profile is configured such that Eclipse compiles to <code>target-ide</code> directory rather than the usual <code>target</code> directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.</p>
</div>
</div>
<div class="sect2">
<h3 id="__dg_building-isis_checking-for-vulnerabilities">4.5. Checking for Vulnerabilities</h3>
<div class="paragraph">
<p>Apache Isis configures the <a href="https://www.owasp.org/index.php/Main_Page">OWASP</a> <a href="https://www.owasp.org/index.php/OWASP_Dependency_Check">dependency check</a> <a href="http://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html">Maven plugin</a> to determine whether the framework uses libraries that are known to have security vulnerabilities.</p>
</div>
<div class="paragraph">
<p>To check, run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">mvn org.owasp:dependency-check-maven:aggregate -Dowasp</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will generate a single report under <code>target/dependency-check-report.html</code>.</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>The first time this runs can take 10~20 minutes to download the NVD data feeds.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>To disable, either run in offline mode (add <code>-o</code> or <code>--offline</code>) or omit the <code>owasp</code> property.</p>
</div>
</div>
<div class="sect2">
<h3 id="__dg_building-isis_checking-for-use-of-internal-jdk-apis">4.6. Checking for use of internal JDK APIs</h3>
<div class="paragraph">
<p>Apache Isis configures the <a href="https://maven.apache.org/plugins-archives/maven-jdeps-plugin-3.0.0/">jdeps maven plugin</a> to check for any usage of internal JDK APIs. This is in preparation for Java 9 module system (Jigsaw) which will prevent such usage of APIs.</p>
</div>
<div class="paragraph">
<p>To check, run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">mvn clean install -Djdeps</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will fail the build on any module that currently uses an internal JDK API.</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>At the time of writing the <code>isis-core-schema</code> module fails the build.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_asciidoc">5. AsciiDoc Documentation</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>Apache Isis' documentation (meaning the website and the users' guide, the reference guide and this contributors' guide) is written using <a href="http://www.methods.co.nz/asciidoc/">Asciidoc</a>, specifically the <a href="http://asciidoctor.org/">Asciidoctor</a> implementation.</p>
</div>
<div class="paragraph">
<p>The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides. You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).</p>
</div>
<div class="paragraph">
<p>To help write the Asciidoc text itself, we provide some <a href="../dg/dg.html#_dg_asciidoc-templates">Asciidoc templates</a>.</p>
</div>
<div class="paragraph">
<p>Publishing is performed by copying the generated HTML to a different git repository (<a href="https://git-wip-us.apache.org/repos/asf?p=isis-site.git">isis-site</a>). Since this can only be done by Apache Isis committers, the process for doing this is described in the <a href="../cgcom/cgcom.html#_cgcom_asciidoc-publish-procedure">committers' guide</a>. This is synced by ASF infrastructure over to <a href="http://isis.apache.org">isis.apache.org</a>.</p>
</div>
<div class="sect2">
<h3 id="_where_to_find_the_docs">5.1. Where to find the Docs</h3>
<div class="paragraph">
<p>The (Asciidoc) source code can be found at <code>adocs/documentation</code> (relative to root). Online you’ll find it <a href="https://github.com/apache/isis/tree/master/adocs/documentation">cloned to github here</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dg_asciidoc_naming-conventions">5.2. Naming Conventions</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_naming-conventions.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_naming-conventions.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_naming-conventions.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_naming-conventions.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_naming-conventions.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>For documents with inclusions, use '_' to separate out the logical hierarchy:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>xxx-xxx/xxx-xxx.adoc
_xxx-xxx_ppp-ppp.adoc
_xxx-xxx_qqq-qqq.adoc
_xxx-xxx_qqq-qqq_mmm-mmm.adoc
_xxx-xxx_qqq-qqq_nnn-nnn.adoc</code></pre>
</div>
</div>
<div class="paragraph">
<p>Any referenced images should be in subdirectories of the <code>images</code> directory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>xxx-xxx/images/.
/ppp-ppp/.
/qqq-qqq/.
/mmm-mmm
/nnn-nnn</code></pre>
</div>
</div>
<div class="paragraph">
<p>And similarly any resources should be in the <code>resources</code> subdirectory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>xxx-xxx/resources/.
ppp-ppp/.
qqq-qqq/.
/mmm-mmm/
/nnn-nnn/</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_dg_asciidoc_writing-the-docs">5.3. Writing the docs</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>We highly recommend that you install the (IntelliJ) live templates for Asciidoctor, as described in <a href="../dg/dg.html#__dg_ide_intellij_live-templates">IDE templates</a>. These provide a large number of helper templates.</p>
</div>
<div class="paragraph">
<p>An <a href="../dg/dg.html#_dg_asciidoc-templates">appendix</a> lists all the templates available, demonstrating their intended usage and output.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dg_asciidoc_build-and-review">5.4. Build and Review (using Maven)</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_build-and-review.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_build-and-review.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_build-and-review.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_build-and-review.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_build-and-review.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>To (re)build the documentation locally prior to release, change into the <code>adocs/documentation</code> directory and use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>mvn clean compile</code></pre>
</div>
</div>
<div class="paragraph">
<p>The site will be generated at <code>target/site/index.html</code>.</p>
</div>
<div class="paragraph">
<p>You could then use a web server such as Python’s SimpleHTTPServer to preview (so that all Javascript works correctly). However, instead we recommend using instant preview, described next.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dg_asciidoc_instant-rebuild">5.5. Instant Rebuild (using Ruby)</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_instant-rebuild.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_instant-rebuild.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_instant-rebuild.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_instant-rebuild.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_instant-rebuild.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>The ruby script, <code>monitor.rb</code> emulates the <code>mvn compile</code> command, regenerating any changed Asciidoctor files to the relevant <code>target/site</code> directory. Moreover if any included files are changed then it rebuilds the parent (per the above naming convention).</p>
</div>
<div class="sect3">
<h4 id="_one_time_setup">5.5.1. One-time setup</h4>
<div class="paragraph">
<p>To setup:</p>
</div>
<div class="ulist">
<ul>
<li> <p>download and install ruby 2.0.0, from <a href="http://rubyinstaller.org/downloads">http://rubyinstaller.org/downloads/</a></p> </li>
<li> <p>download devkit for the Ruby 2.0 installation, also from <a href="http://rubyinstaller.org/downloads">http://rubyinstaller.org/downloads/</a>. Then follow the <a href="https://github.com/oneclick/rubyinstaller/wiki/Development-Kit">installation instructions</a> on their wiki</p> </li>
</ul>
</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>We use Ruby 2.0 rather than 2.1 because the wdm gem (required to monitor the filesystem if running on Windows) is not currently compatible with Ruby 2.1.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>To download the required Ruby dependencies, use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">gem install bundler
bundle install</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_instant_rebuild">5.5.2. Instant Rebuild</h4>
<div class="paragraph">
<p>To run, we typically just use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">sh preview-html.sh</code></pre>
</div>
</div>
<div class="paragraph">
<p>This script just runs <code>mvn compile</code> for HTML files only, then calls <code>python</code> to start the web browser and run a simple web server (on port 8000).</p>
</div>
<div class="paragraph">
<p>If you want to double-check the PDFs also, then use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">sh preview-pdf.sh</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_dg_asciidoc_publish-procedure">5.6. Publish procedure</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="paragraph">
<p>Only Apache Isis committers can publish to <a href="http://isis.apache.org">isis.apache.org</a>. See the <a href="../cgcom/cgcom.html#_cgcom_asciidoc-publish-procedure">committers' guide</a> for further details.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_contributing">6. Contributing</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>This page explains how you can contribute to Apache Isis. You’ll probably also want <a href="../dg/dg.html#_dg_ide">set up your IDE</a> and learn <a href="../dg/dg.html#_dg_building-isis">how to build Apache Isis</a>.</p>
</div>
<div class="paragraph">
<p>Thanks for considering to help out, your contributions are appreciated!</p>
</div>
<div class="sect2">
<h3 id="_recommended_workflow_github">6.1. Recommended Workflow (github)</h3>
<div class="paragraph">
<p>Apache Isis' source code is hosted in an Apache git repo (<a href="https://git-wip-us.apache.org/repos/asf/isis.git">https</a>, <a href="http://git-wip-us.apache.org/repos/asf/isis.git">http</a>), with a clone on github (<a href="https://github.com/apache/isis.git">https</a>, or ssh: <code>git@github.com:apache/isis.git</code>.</p>
</div>
<div class="paragraph">
<p>As you might imagine, only committers are permitted to push changes to the central git repo. As a contributor, we recommend that you fork the <a href="https://github.com/apache/isis.git">apache/isis</a> repo in github, and then use your fork as a way of publishing your patches for the Apache Isis committers to apply.</p>
</div>
<div class="paragraph">
<p>The diagram below illustrates the process:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/contributing/git-workflow.png"><img src="images/contributing/git-workflow.png" alt="git workflow" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>That is:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li> <p>as a one-time activity, you fork the <a href="https://github.com/apache/isis.git">github.com/apache/isis</a> repo into your own fork on github.com</p> </li>
<li> <p>as a one-time activity, you clone your fork to your local computer</p> </li>
<li> <p>you set the <a href="https://github.com/apache/isis.git">github.com/apache/isis</a> as your upstream branch; this will allow you to keep your local clone up-to-date with new commits</p>
<div class="ulist">
<ul>
<li> <p>note the asymmetry here: the <code>upstream</code> repo (the Apache github repo) is <strong>not</strong> the same as the <code>origin</code> repo (your fork).</p> </li>
</ul>
</div> </li>
<li> <p>you work on your changes locally; when done, you push them to your github fork</p> </li>
<li> <p>to contribute back a change, raise a <a href="https://issues.apache.org/jira/browse/ISIS">JIRA</a> ticket, and ensure your commit message is in the form: <code>ISIS-nnnn: …</code> so that changes can be tracked (more discussion on this point below). In any case, before you decide to start hacking with Apache Isis, it’s always worth creating a ticket in JIRA and then have a discussion about it on the <a href="../../support.html">mailing lists</a>.</p> </li>
<li> <p>Use github to raise a <a href="https://help.github.com/articles/using-pull-requests/">pull request</a> for your feature</p> </li>
<li> <p>An Apache Isis committer will review your change, and apply it if suitable.</p> </li>
</ol>
</div>
</div>
<div class="sect2">
<h3 id="_alternative_workflow_jira_patches">6.2. Alternative Workflow (JIRA patches)</h3>
<div class="paragraph">
<p>As an alternative, you may decide to clone directly from <a href="https://github.com/apache/isis.git">github.com/apache/isis</a> rather than create your own fork:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/contributing/git-workflow-2.png"><img src="images/contributing/git-workflow-2.png" alt="git workflow 2" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>In this case your <code>upstream</code> repo is the same as your <code>origin</code> repo, which might seem more straightforward. On the other hand, if you go this route then you’ll need create patches locally and attach them to the JIRA ticket.</p>
</div>
<div class="paragraph">
<p>For the Apache Isis committers it really doesn’t matter which route you take, so go with whatever’s most comfortable.</p>
</div>
</div>
<div class="sect2">
<h3 id="_setting_up_your_fork_clone">6.3. Setting up your fork/clone</h3>
<div class="paragraph">
<p>If you choose to create your own fork then you’ll need an account on <a href="https://github.com">github.com</a>. You then fork simply by pressing the "Fork" button:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/contributing/github-forking.png"><img src="images/contributing/github-forking.png" alt="github forking" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>An account isn’t needed if you just clone straight from the <a href="http://github.com/apache/isis">github.com/apache/isis</a>.</p>
</div>
<div class="paragraph">
<p>Whether you’ve forked or not, you then need to clone the repo onto your computer. Github makes this very easy to do:</p>
</div>
<div class="ulist">
<ul>
<li> <p>for Windows users, we suggest you use github’s 'Clone in Windows' feature</p> </li>
<li> <p>for Mac/Linux users, create a clone from the command line:</p> </li>
</ul>
</div>
<div class="paragraph">
<p>Again, the info is easily found in the github page:</p>
</div>
<div class="imageblock">
<div class="content">
<a class="image" href="images/contributing/github-cloning.png"><img src="images/contributing/github-cloning.png" alt="github cloning" width="600px"></a>
</div>
</div>
<div class="paragraph">
<p>If you’ve created your own fork, then you need to add the <code>upstream</code> remote to the <a href="https://github.com/apache/isis">github.com/apache/isis</a>. This remote is traditionally called <code>upstream</code>. You should then arrange for your <code>master</code> branch to track the <code>upstream/master</code> remote branch:</p>
</div>
<div class="paragraph">
<p>If you didn’t create your own fork, you can omit the above step. Either way around, you can now fetch new commits using simply:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git fetch</code></pre>
</div>
</div>
<div class="paragraph">
<p>For more info on tracking branches <a href="http://git-scm.com/book/en/Git-Branching-Remote-Branches">here</a> and <a href="http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html">here</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_commit_messages">6.4. Commit messages</h3>
<div class="paragraph">
<p>Although with git your commits are always performed on your local repo, those commit messages become public when the patch is applied by an Apache Isis committer. You should take time to write a meaningful commit message that helps explain what the patch refers to; if you don’t then there’s a chance that your patch may be rejected and not applied. No-one likes hard work to go to waste!</p>
</div>
<div class="paragraph">
<p>We therefore recommend that your commit messages are as follows [1]:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="other">ISIS-999: Make the example in CONTRIBUTING imperative and concrete
Without this patch applied the example commit message in the CONTRIBUTING
document is not a concrete example. This is a problem because the
contributor is left to imagine what the commit message should look like
based on a description rather than an example. This patch fixes the
problem by making the example concrete and imperative.
The first line is a real life imperative statement with a ticket number
from our issue tracker. The body describes the behavior without the patch,
why this is a problem, and how the patch fixes the problem when applied.</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_creating_the_patch_file">6.5. Creating the patch file</h3>
<div class="paragraph">
<p>If you are working without a github fork of Apache Isis, then you can create the patches from your own local git repository.</p>
</div>
<div class="paragraph">
<p>As per <a href="http://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit">this stackoverflow question</a>, create the patch using <code>git format-patch</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here <code>-10</code> is the last 10 commits you have done. You need to change that integer according to the commits you need to apply into the patch.</p>
</div>
</div>
<div class="sect2">
<h3 id="_sample_contribution_workflow">6.6. Sample Contribution Workflow</h3>
<div class="paragraph">
<p>Assuming you’re development environment is all setup, let’s walk through how you might make contribute a patch. In this example, suppose that you’ve decided to work on JIRA ticket #123, an enhancement to support Blob/Clob datatypes.</p>
</div>
<div class="sect3">
<h4 id="_update_your_master_branch">6.6.1. Update your master branch</h4>
<div class="paragraph">
<p>The first thing to do is to make sure your local clone is up-to-date. We do this by retrieving new commits from upstream repo and then merging them as a fast-forward into your local branch.</p>
</div>
<div class="paragraph">
<p>Irrespective of whether you are using a github fork, the upstream for your local <code>master</code> branch will be tracking the appropriate remote’s <code>master</code> branch. So n either case, the same commands work:</p>
</div>
<div class="paragraph">
<p>Alternatively, you can combine the <code>git fetch</code> and <code>git merge</code> and just use <code>git pull</code>: <pre> git checkout master git pull –ff-only </pre></p>
</div>
<div class="paragraph">
<p>If the <code>merge</code> or <code>pull</code> fails, it means that you must have made commits and there have been changes meanwhile on the remote <code>master’s branch. You can use `gitk --all</code> to confirm. If this fails, see our <a href="#">git cookbook</a> page for a procedure to retrospectively sort out this situation.</p>
</div>
</div>
<div class="sect3">
<h4 id="_create_a_topic_branch">6.6.2. Create a topic branch</h4>
<div class="paragraph">
<p>We recommend you name topic branches by the JIRA ticket, ie <tt>ISIS-nnn-description</tt>. So let’s create a new branch based off <code>master</code> and call it "ISIS-123-blobs"</p>
</div>
<div class="paragraph">
<p>You can confirm the branch is there and is your new <code>HEAD</code> using either <code>gitk --all</code>. Alternatively, use the command line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ git checkout -b ISIS-123-blobs</code></pre>
</div>
</div>
<div class="paragraph">
<p>The command line prompt should also indicate you are on a branch, isolated from any changes that might happen on the <code>master</code> branch.</p>
</div>
</div>
<div class="sect3">
<h4 id="_make_file_changes_and_commit">6.6.3. Make File Changes and Commit</h4>
<div class="paragraph">
<p>Next, make changes to your files using the usual commands (see also our <a href="../dg/dg.html#_dg_git-cookbook">git cookbook</a> section):</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>git add</code></p> </li>
<li> <p><code>git mv</code></p> </li>
<li> <p><code>git rm</code></p> </li>
<li> <p><code>git commit</code></p> </li>
<li> <p><code>git status</code></p> </li>
</ul>
</div>
<div class="paragraph">
<p>and so on.</p>
</div>
<div class="paragraph">
<p>Continue this way until happy with the change. Remember to run all your tests on the topic branch (including a full <code>mvn clean install</code>).</p>
</div>
</div>
<div class="sect3">
<h4 id="_rebasing_with_code_master_code">6.6.4. Rebasing with <code>master</code></h4>
<div class="paragraph">
<p>Before you can share your change, you should rebase (in other words replay) your changes on top of the <code>master</code> branch.</p>
</div>
<div class="paragraph">
<p>The first thing to do is to pull down any changes made in upstream remote’s <code>master</code> since you started your topic branch:</p>
</div>
<div class="paragraph">
<p>These are the same commands that you would have run before you created your topic branch. If you use <code>gitk --all</code>, there’s a good chance that new commits have come in.</p>
</div>
<div class="paragraph">
<p>Next, we reintegrate our topic branch by rebasing onto <code>master</code>: <pre> git checkout ISIS-123-blobs git rebase master </pre></p>
</div>
<div class="paragraph">
<p>This takes all of the commits in your branch, and applies them on top of the new <code>master</code> branch. When your change is eventually integrated back in, it will result in a nice clear linear history on the public repo.</p>
</div>
<div class="paragraph">
<p>If the rebase fails because of a conflict, then you’ll be dumped into REBASE mode. Edit the file that has the conflict, and make the appropriate edits. Once done:</p>
</div>
<div class="paragraph">
<p>Once the rebase has completed, re-run your tests to confirm that everything is still good.</p>
</div>
</div>
<div class="sect3">
<h4 id="_raising_a_pull_request">6.6.5. Raising a pull request</h4>
<div class="paragraph">
<p>If you have your own fork, you can now simply push the changes you’ve made locally to your fork:</p>
</div>
<div class="paragraph">
<p>This will create a corresponding branch in the remote github repo. If you use <code>gitk --all</code>, you’ll also see a <code>remotes/origin/ISIS-123-blobs</code> branch.</p>
</div>
<div class="paragraph">
<p>Then, use github to raise a <a href="https://help.github.com/articles/using-pull-requests/">pull request</a>. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the <a href="../../support.html">dev mailing list</a>. You’ll probably want to sign up to the dev mailing list first before issuing your first pull request (though that isn’t mandatory).</p>
</div>
<div class="paragraph">
<p>The process to raise the pull request, broadly speaking:</p>
</div>
<div class="ulist">
<ul>
<li> <p>Open a web browser to your github fork of isis</p> </li>
<li> <p>Select your topic branch (pushed in the previous step) so that the pull request references the topic branch.</p> </li>
<li> <p>Click the <code>Pull Request</code> button.</p> </li>
<li> <p>Check that the Apache Isis mailing list email came through.</p> </li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_if_your_pull_request_is_accepted">6.7. If your pull request is accepted</h3>
<div class="paragraph">
<p>To double check that your pull request is accepted, update your <code>master</code> branch from the <code>upstream</code> remote:</p>
</div>
<div class="paragraph">
<p>You can then use <code>gitk --all</code> (or <code>git log</code> if you prefer the command line) to check your contribution has been added.</p>
</div>
<div class="paragraph">
<p>You can now delete your topic branch and remove the branch in your github:</p>
</div>
<div class="paragraph">
<p>Finally, you might want to push the latest changes in master back up to your github fork. If so, use:</p>
</div>
<div class="sect3">
<h4 id="_if_your_pull_request_is_rejected">6.7.1. If your pull request is rejected</h4>
<div class="paragraph">
<p>If your pull request is rejected, then you’ll need to update your branch from the main repository and then address the rejection reason.</p>
</div>
<div class="paragraph">
<p>You’ll probably also want to remove the remote branch on github:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git push origin –delete ISIS-123-blobs</code></pre>
</div>
</div>
<div class="paragraph">
<p>… and continue as before until you are ready to resubmit your change.</p>
</div>
<div class="paragraph">
<p>[1] inspiration for the recommended commit format comes from the <a href="https://github.com/puppetlabs/puppet">puppet</a> project’s <a href="https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md">contributing</a> page.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_git-cookbook">7. Appendix: Git Cookbook</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>This appendix describes the commands often used while working with git. In addition to these basic commands, please make sure you have read:</p>
</div>
<div class="ulist">
<ul>
<li> <p><a href="../dg/dg.html#_dg_building-isis">building Apache Isis</a></p> </li>
<li> <p><a href="../dg/dg.html#_dg_contributing">Contributing</a></p> </li>
<li> <p><a href="../cgcom/cgcom.html#_cgcom_policies_git-policy">Git policy</a></p> </li>
</ul>
</div>
<div class="sect2">
<h3 id="_modifying_existing_files">7.1. Modifying existing files</h3>
<div class="paragraph">
<p>To modify existing files:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git add filename
git commit -m "ISIS-nnn: yada yada"</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>git add</code> command adds the changes to the file(s) to the git index (aka staging area). If you were to make subsequent changes to the file these would not be committed.</p>
</div>
<div class="paragraph">
<p>The <code>git commit</code> takes all the staged changes and commits them locally. Note that these changes are not shared public with Apache Isis' central git repo.</p>
</div>
<div class="paragraph">
<p>You can combine these two commands using <code>-am</code> flag to git commit:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git commit -am "ISIS-nnn: yada yada"</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_adding_new_files">7.2. Adding new files</h3>
<div class="paragraph">
<p>To add a new file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git add .
git commit -m "ISIS-nnn: yada yada"</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that this sequence of commands is identical to modifying an existing file. However, it isn’t possible to combine the two steps using <code>git commit -am</code>; the <code>git add</code> is always needed when adding new files to the repo.</p>
</div>
</div>
<div class="sect2">
<h3 id="_deleting_files">7.3. Deleting files</h3>
<div class="paragraph">
<p>To delete a file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git rm filename
git commit -m "ISIS-nnn: yada yada"</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_renaming_or_moving_files">7.4. Renaming or moving files</h3>
<div class="paragraph">
<p>To rename or move a file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git mv <i>filename</i> <i>newfilename</i>
git commit -m "ISIS-nnn: yada yada"</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_common_workflows">7.5. Common Workflows</h3>
<div class="paragraph">
<p>The <a href="../dg/dg.html#_dg_contributing">contributing</a> page describes the workflow for non-committers. The <a href="../cgcom/cgcom.html#_cgcom_policies_git-policy">Git policy</a> page describes a workflow for Apache Isis <strong>committers</strong>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_backing_up_a_local_branch">7.6. Backing up a local branch</h3>
<div class="paragraph">
<p>If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.</p>
</div>
<div class="paragraph">
<p>To create a new, similarly named branch on the central repo, use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git push -u origin <i>branchname</i></code></pre>
</div>
</div>
<div class="paragraph">
<p>Using <code>gitk --all</code> will show you this new branch, named <strong>origin/branchname</strong>.</p>
</div>
<div class="paragraph">
<p>Thereafter, you can push subsequent commits using simply:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git push</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this also allows others to collaborate on this branch, just as they would for <code>master</code>.</p>
</div>
<div class="paragraph">
<p>When, eventually, you have reintegrated this branch, you can delete the remote branch using:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git push origin --delete <i>branchname</i></code></pre>
</div>
</div>
<div class="paragraph">
<p>For more detail, see this <a href="http://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-both-locally-and-in-github">stackoverflow post</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_quick_change_stashing_changes">7.7. Quick change: stashing changes</h3>
<div class="paragraph">
<p>If you are working on something but are not ready to commit, then use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git stash</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you use <code>gitk --all</code> then you’ll see new commits are made that hold the current state of your working directory and staging area.</p>
</div>
<div class="paragraph">
<p>You can then, for example, pull down the latest changes using <code>git pull --rebase</code> (see above).</p>
</div>
<div class="paragraph">
<p>To reapply your stash, then use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git stash pop</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that stashing works even if switching branches</p>
</div>
</div>
<div class="sect2">
<h3 id="_ignoring_files">7.8. Ignoring files</h3>
<div class="paragraph">
<p>Put file patterns into <code>.gitignore</code>. There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).</p>
</div>
<div class="paragraph">
<p>See also:</p>
</div>
<div class="ulist">
<ul>
<li> <p><a href="https://help.github.com/articles/ignoring-files">github’s help page</a></p> </li>
<li> <p><a href="http://www.kernel.org/pub/software/scm/git/docs/gitignore.html">man page</a></p> </li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_more_advanced_use_cases">7.9. More advanced use cases</h3>
<div class="sect3">
<h4 id="_if_accidentally_push_to_remote">7.9.1. If accidentally push to remote</h4>
<div class="paragraph">
<p>Suppose you committed to <code>master</code>, and then pushed the change, and then decided that you didn’t intend to do that:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">C1 - C2 - C3 - C4 - C5 - C6 - C7
^
master
^
origin/master</code></pre>
</div>
</div>
<div class="paragraph">
<p>To go back to an earlier commit, first we wind back the local <code>master</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git reset --hard C5</code></pre>
</div>
</div>
<div class="paragraph">
<p>where <code>C5</code> is the long sha-id for that commit.</p>
</div>
<div class="paragraph">
<p>This gets us to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">C1 - C2 - C3 - C4 - C5 - C6 - C7
^
master
^
origin/master</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then, do a force push:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git push origin master --force</code></pre>
</div>
</div>
<div class="paragraph">
<p>If this doesn’t work, it may be that the remote repo has disabled this feature. There are other hacks to get around this, see for example <a href="http://stackoverflow.com/questions/1377845/git-reset-hard-and-a-remote-repository">here</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_if_you_ve_accidentally_worked_on_code_master_code_branch">7.10. If you’ve accidentally worked on <code>master</code> branch</h3>
<div class="paragraph">
<p>If at any time the <code>git pull</code> from your upstream fails, it most likely means that you must have made commits on the <code>master</code> branch. You can use <code>gitk --all</code> to confirm; at some point in time both <code>master</code> and <code>origin\master</code> will have a common ancestor.</p>
</div>
<div class="paragraph">
<p>You can retrospectively create a topic branch for the work you’ve accidentally done on <code>master</code>.</p>
</div>
<div class="paragraph">
<p>First, create a branch for your current commit:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git branch <i>newbranch</i></code></pre>
</div>
</div>
<div class="paragraph">
<p>Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git stash</code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally, locate the shaId of the commit you want to roll back to (easily obtained in <code>gitk -all</code>), and wind <code>master</code> branch back to that commit:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git checkout master
git reset --hard <i>shaId</i> # move master branch shaId of common ancestor</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_if_you_ve_forgotten_to_prefix_your_commits_but_not_pushed">7.11. If you’ve forgotten to prefix your commits (but not pushed)</h3>
<div class="paragraph">
<p>One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow. Using one of these, <code>git prefix</code>, you can just commit with proper message without bothering about prefix and add prefix only in the end <strong>before</strong> the final push.</p>
</div>
<div class="paragraph">
<p>For example, to prefix all not yet prefixed commits <code>master..isis/666</code> with <code>ISIS-666</code> prefix, use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git prefix ISIS-666 master..isis/666</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can grab this utility, and others, from <a href="https://github.com/themalkolm/git-boots">this repo</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_working-with-many-repos">8. Appendix: Working with Many Repos</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>Applications built with Apache Isis often (should) consist of multiple modules. For example, there are the various modules that make up the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> that provide various technical/cross-cutting concerns and generic business functionality.</p>
</div>
<div class="paragraph">
<p>In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the <a href="../ugfun/ugfun.html#_ugfun_building-blocks_events_domain-events">event bus</a> and <a href="../ugfun/ugfun.html#_ugfun_building-blocks_types-of-domain-objects_mixins">mixins</a> so that these modules are decoupled from each other.</p>
</div>
<div class="paragraph">
<p>All of which is a preamble to say that you will likely have multiple directories on your local development computer, for each such git repository that you contribute to.</p>
</div>
<div class="paragraph">
<p>In this appendix we provide some simple but useful bash scripts to help you manage each such.</p>
</div>
<div class="sect2">
<h3 id="_prerequisites">8.1. Prerequisites</h3>
<div class="paragraph">
<p>We recommend that you adopt a convention for your directories. For example, open source repositories (such as Apache Isis itself or the Incode Platform) reside in <a href="https://github.com/">github.com</a>, while your own proprietary code might reside in some other service, eg <a href="https://bitbucket.org/">bitbucket</a>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>/users/home/me/
BITBUCKET/
mycompany/
myapp/
otherapp/
GITHUB/
apache/
isis/
incodehq/
incode-platform/</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__code_repos_txt_code">8.2. <code>_repos.txt</code></h3>
<div class="paragraph">
<p>Create a file <code>_repos.txt</code> that catalogues the repositories, eg:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>#
# our code
#
/users/home/me/BITBUCKET/mycompany/myapp
/users/home/me/BITBUCKET/mycompany/otherapp
#
# open source modules
#
/users/home/me/GITHUB/apache/isis
/users/home/me/GITHUB/incodehq/incode-platform</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_bash_functions">8.3. Bash functions</h3>
<div class="paragraph">
<p>The <code>.bash_functions</code> file (downloadable from this <a href="https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c91cb">gist</a>) provides the following two functions:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>repo</code><br></p>
<div class="paragraph">
<p>Switches (using <code>pushd</code>) to the specified directory (as listed in the <code>_repos.txt</code> file).</p>
</div> </li>
<li> <p><code>foreach</code><br></p>
<div class="paragraph">
<p>Runs the specified command for all (or matching) repositories (as listed in <code>_repos.txt</code> file).</p>
</div> </li>
</ul>
</div>
<div class="paragraph">
<p>For example,</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">repo plat</code></pre>
</div>
</div>
<div class="paragraph">
<p>would switch to <code>/users/home/me/GITHUB/incodehq/incode-platform</code>, the first module that matches the fragment.</p>
</div>
<div class="paragraph">
<p>Meanwhile:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">foreach git status</code></pre>
</div>
</div>
<div class="paragraph">
<p>would perform a <code>git status</code> on every git repository, while</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">foreach -g plat git fetch</code></pre>
</div>
</div>
<div class="paragraph">
<p>would perform a <code>git fetch</code> but only to those repositories which match "plat" (<code>-g</code> flag standing for <code>grep</code>).</p>
</div>
<div class="paragraph">
<p>To load the functions into your profile (<code>.bashrc</code> or <code>.profile</code> or similar), use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">. ~/.bash_functions</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_asciidoc-syntax">9. Appendix: Asciidoc Syntax</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>This appendix describes the main syntax conventions when writing Asciidoctor/Asciidoc.</p>
</div>
<div class="paragraph">
<p>For more info, see:</p>
</div>
<div class="ulist">
<ul>
<li> <p><a href="resources/asciidoc-syntax-quick-reference.pdf">asciidoc-syntax-quick-reference.pdf</a></p> </li>
<li> <p><a href="resources/asciidoc-writers-guide.pdf">asciidoc-writers-guide.pdf</a></p> </li>
<li> <p><a href="https://powerman.name/doc/asciidoc">online cheat sheet</a></p> </li>
<li> <p><a href="http://asciidoctor.org/docs/user-manual">asciidoctor online user manual</a></p> </li>
<li> <p><a href="http://www.methods.co.nz/asciidoc/userguide.html">asciidoc online user manual</a></p> </li>
</ul>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc-syntax_headings">9.1. Headings</h3>
<div class="paragraph">
<p>The number of preceding <code>=</code> signs indicates the heading level.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 60%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syntax</th>
<th class="tableblock halign-left valign-top">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>= Level 1</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>There can only be one level 1 per .adoc (at the very top).</p>
</div>
<div class="paragraph">
<p>The paragraph immediately following the heading is the "preamble", and is rendered in a larger font. It’s therefore a good place to summarize the content of the document.</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>== Level 2</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Level 2</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>=== Level 3</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Level 3</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>==== Level 4</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Level 4</p>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_paragraphs">9.2. Paragraphs</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 60%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syntax</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>Paragraphs are separated by one or more blank lines.
So, this is a separate paragraph.</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Paragraphs are separated by one or more blank lines.</p>
</div>
<div class="paragraph">
<p>So, this is a separate paragraph.</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>All consecutive sentences are rendered in the same paragraph.
This is another sentence in the para.
And another one.
Yet another.</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Sentences without a blank line are in the same paragraph. Don’t worry about word wrapping, just start the next sentence on the next line.</p>
</div>
</div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In general, there’s no need to indent paragraphs; keep things left-aligned. Let the markup specify the logical indentation.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">
Start each sentence on a new line
</div>
<div class="paragraph">
<p>Don’t worry about wrapping sentences at 80 characters, just start each new sentence on a new line. Asciidoc will take care of the rendering.</p>
</div>
<div class="paragraph">
<p>This simple tip has a number of other benefits:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li> <p>when the document is edited (eg correct a typo or insert a missing word), then only a single line in the file is changed.<br></p>
<div class="paragraph">
<p>This will reduce change of merge conflicts, too.</p>
</div> </li>
<li> <p>You can easily see if a sentence is too long, and should be split</p> </li>
<li> <p>You can easily see if all sentences are the same length: good writing should vary the length of sentences</p> </li>
<li> <p>You can easily see if successive sentences start with the same phrase (that might be a good thing, or a bad thing, depending).</p> </li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_bulleted-lists">9.3. Bulleted lists</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 60%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syntax</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>The blank line after this para is required:
* Bullet 1 +
+
Indented paragraph (note the '+' to to chain this para with the bullet)
* Bullet 2
** Child bullets +
+
More indenting
** Another child bullet
* Bullet 3</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>The blank line after this para is required:</p>
</div>
<div class="ulist">
<ul>
<li> <p>Bullet 1<br></p>
<div class="paragraph">
<p>Indented paragraph (note the '+' to chain this para with the bullet)</p>
</div> </li>
<li> <p>Bullet 2</p>
<div class="ulist">
<ul>
<li> <p>Child bullets<br></p>
<div class="paragraph">
<p>More indenting</p>
</div> </li>
<li> <p>Another child bullet</p> </li>
</ul>
</div> </li>
<li> <p>Bullet 3</p> </li>
</ul>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_numbered-lists">9.4. Numbered lists</h3>
<div class="paragraph">
<p>There’s no need to keep track of numbers, just use '1' or 'a' etc:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 60%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syntax</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>The blank line after this para is required:
1. Bullet 1 +
+
Indented paragraph
2. Bullet 2
a. Child bullets +
+
More indenting
b. Another child bullet
3. Bullet 3</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>The blank line after this para is required:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li> <p>Bullet 1<br></p>
<div class="paragraph">
<p>Indented paragraph</p>
</div> </li>
<li> <p>Bullet 2</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li> <p>Child bullets<br></p>
<div class="paragraph">
<p>More indenting</p>
</div> </li>
<li> <p>Another child bullet</p> </li>
</ol>
</div> </li>
<li> <p>Bullet 3</p> </li>
</ol>
</div>
</div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>While it isn’t necessary to maintain the ordering manually (could just use '1' for all bullets), this does generate warnings when the document is built.</p>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_links-and-xrefs">9.5. Links and Cross-references</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 37.5%;">
<col style="width: 25%;">
<col style="width: 37.5%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syntax</th>
<th class="tableblock halign-left valign-top">Example</th>
<th class="tableblock halign-left valign-top">Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>link:http://ciserver:8080[CI Server]</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="http://ciserver:8080">CI Server</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Link to an external hyperlink</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>link:http://ciserver:8080[CI Server^]</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="http://ciserver:8080" target="_blank">CI Server</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Link to an external hyperlink, with <code>target=blank</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>xref:dg.adoc#__dg_asciidoc_links-and-xrefs#[background]</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="#__dg_asciidoc_links-and-xrefs">background</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Cross-reference to section in same asciidoc document</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>xref:../ugfun/ugfun.adoc#[Fundamentals]</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugfun/ugfun.html">Fundamentals</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Cross-reference to top-level of different asciidoc document</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>xref:../ugfun/ugfun.adoc#_ugfun_core-concepts[Core Concepts]</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugfun/ugfun.html#_ugfun_core-concepts">Core Concepts</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Cross-reference to section within different asciidoc document</p>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_tables">9.6. Tables</h3>
<div class="literalblock">
<div class="content">
<pre>.Some table
[cols="3a,2a", options="header"]
|===
| Header col 1
| Header col 2
| Row 1 col 1
| Row 1 col 2
| Row 2 col 1
| Row 2 col 2
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 1. Some table
</caption>
<colgroup>
<col style="width: 60%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Header col 1</th>
<th class="tableblock halign-left valign-top">Header col 2</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Row 1 col 1</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Row 1 col 2</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Row 2 col 1</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Row 2 col 2</p>
</div>
</div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p>the <code>cols</code> attribute says how many columns there are and their respective widths.</p> </li>
<li> <p>the "a" suffix indicates that the contents is parsed as Asciidoc</p> </li>
</ul>
</div>
<div class="sect3">
<h4 id="_column_attributes">9.6.1. Column Attributes</h4>
<div class="paragraph">
<p>Other options are (<a href="http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-styling-columns-and.html">credit</a>):</p>
</div>
<div class="ulist">
<ul>
<li> <p>e: emphasized</p> </li>
<li> <p>a: Asciidoc markup</p> </li>
<li> <p>m: monospace</p> </li>
<li> <p>h: header style, all column values are styled as header</p> </li>
<li> <p>s: strong</p> </li>
<li> <p>l: literal, text is shown in monospace font and line breaks are kept</p> </li>
<li> <p>d: default</p> </li>
<li> <p>v: verse, keeps line breaks</p> </li>
</ul>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>.Table with column style e,a,m
[cols="e,a,m"]
|===
| Emphasized (e) | Asciidoc (a) | Monospaced (m)
| Asciidoctor
| NOTE: *Awesome* way to write documentation
| It is just code
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 2. Table with column style e,a,m
</caption>
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Emphasized (e)</th>
<th class="tableblock halign-left valign-top">Asciidoc (a)</th>
<th class="tableblock halign-left valign-top">Monospaced (m)</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>Asciidoctor</em></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock note">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content"> <strong>Awesome</strong> way to write documentation </td>
</tr>
</tbody>
</table>
</div>
</div></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>It is just code</code></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>and:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>.Table with column style h,s,l
[cols="h,s,l"]
|===
| Header (h) | Strong (s) | Literal (l)
| Asciidoctor
| Awesome way to write documentation
| It is
just code
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 3. Table with column style h,s,l
</caption>
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Header (h)</th>
<th class="tableblock halign-left valign-top">Strong (s)</th>
<th class="tableblock halign-left valign-top">Literal (l)</th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock">Asciidoctor</p></th>
<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Awesome way to write documentation</strong></p></td>
<td class="tableblock halign-left valign-top">
<div class="literal">
<pre>It is
just code</pre>
</div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>and:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>.Table with column style d,v
[cols="d,v"]
|===
| Default (d) | Verse (v)
| Asciidoctor
| Awesome way
to write
documentation
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 4. Table with column style d,v
</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Default (d)</th>
<th class="tableblock halign-left valign-top">Verse (v)</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Asciidoctor</p></td>
<td class="tableblock halign-left valign-top">
<div class="verse">
Awesome way to write documentation
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="_column_alignment">9.6.2. Column Alignment</h4>
<div class="paragraph">
<p>This can be combined with alignment markers (<a href="http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-table-column-and.html">credit</a>):</p>
</div>
<div class="ulist">
<ul>
<li> <p><: top align values (default)</p> </li>
<li> <p>>: bottom align values</p> </li>
<li> <p>^: center values</p> </li>
</ul>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[cols="^.>,<.<,>.^", options="header"]
|===
| Name
| Description
| Version
| Asciidoctor
| Awesome way to write documentation
| 1.5.0
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-bottom">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-right valign-middle">Version</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-bottom"><p class="tableblock">Asciidoctor</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Awesome way to write documentation</p></td>
<td class="tableblock halign-right valign-middle"><p class="tableblock">1.5.0</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p>the first column is centered and bottom aligned,</p> </li>
<li> <p>the second column is left and top aligned and</p> </li>
<li> <p>the third column is right aligned and centered vertically.</p> </li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_column_row_spanning">9.6.3. Column/Row Spanning</h4>
<div class="paragraph">
<p>We can also have columns or rows spanning multiple cells (<a href="http://mrhaki.blogspot.co.uk/2014/12/awesome-asciidoctor-span-cell-over-rows.html">credit</a>):</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>.Cell spans columns
|===
| Name | Description
| Asciidoctor
| Awesome way to write documentation
2+| The statements above say it all
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 5. Cell spans columns
</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Asciidoctor</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Awesome way to write documentation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock">The statements above say it all</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The <code>N+</code> sign notation tells Asciidoctor to span this cell over N columns.</p>
</div>
<div class="paragraph">
<p>while:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>.Cell spans rows
|===
| Name | Description
.2+| Asciidoctor
| Awesome way to write documentation
| Works on the JVM
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 6. Cell spans rows
</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top" rowspan="2"><p class="tableblock">Asciidoctor</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Awesome way to write documentation</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Works on the JVM</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The <code>.N+</code> notation tells Asciidoctor to span this cell over N rows.</p>
</div>
<div class="paragraph">
<p>and:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>.Cell spans both rows and columns
|===
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
2.2+| Cell spans 2 cols, 2 rows
| Row 2, Col 3
| Row 3, Col 3
|===</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
Table 7. Cell spans both rows and columns
</caption>
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Row 1, Col 1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Row 1, Col 2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Row 1, Col 3</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" colspan="2" rowspan="2"><p class="tableblock">Cell spans 2 cols, 2 rows</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Row 2, Col 3</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Row 3, Col 3</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The <code>N.M+</code> notation tells Asciidoctor to span this cell over N columns and M rows.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_admonitions">9.7. Admonitions</h3>
<div class="paragraph">
<p>Callout or highlight content of particular note.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 60%;">
<col style="width: 40%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Syntax</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>NOTE: the entire note must be a single sentence.</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock note">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content"> the entire note must be a single sentence. </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[NOTE]
====
the note is multiple paragraphs, and can have all the usual styling,
* eg bullet points:
* etc etc
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<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>the note is multiple paragraphs, and can have all the usual styling,</p>
</div>
<div class="ulist">
<ul>
<li> <p>eg bullet points:</p> </li>
<li> <p>etc etc</p> </li>
</ul>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[TIP]
====
Here's something worth knowing...
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
<p>Here’s something worth knowing…</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[WARNING]
====
Be careful...
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<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>Be careful…</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[IMPORTANT]
====
Don't forget...
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock important">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
<td class="content">
<div class="paragraph">
<p>Don’t forget…</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_source-code">9.8. Source code</h3>
<div class="paragraph">
<p>Use <code>[source]</code> macro to specify source content:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[source,powershell]
----
get-command -module BomiArtifact
----</pre>
</div>
</div>
<div class="paragraph">
<p>will render as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="powershell">get-command -module BomiArtifact</code></pre>
</div>
</div>
<div class="paragraph">
<p>Some languages support syntax highlighting. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[source,java]
----
public class SomeClass extends SomeOtherClass {
...
}
----</pre>
</div>
</div>
<div class="paragraph">
<p>will render as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SomeClass</span> <span class="directive">extends</span> SomeOtherClass {
...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Callouts can also be added using an appropriate comment syntax. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[source,java]
----
public class SomeClass
extends SomeOtherClass { // <1>
public static void main(String[] args) { // <2>
...
}
}
----
<1> inherits from `SomeOtherClass`
<2> entry point into the program</pre>
</div>
</div>
<div class="paragraph">
<p>will render as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SomeClass</span>
<span class="directive">extends</span> SomeOtherClass { <i class="conum" data-value="1"></i><b>(1)</b>
<span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) { <i class="conum" data-value="2"></i><b>(2)</b>
...
}
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tbody>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>inherits from <code>SomeOtherClass</code></td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>entry point into the program</td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>and</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[source,xml]
----
<a>
<b c="foo"> <!--1-->
</a>
----
<1> some comment</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><a></span>
<span class="tag"><b</span> <span class="attribute-name">c</span>=<span class="string"><span class="delimiter">"</span><span class="content">foo</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b>
<span class="tag"></a></span></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tbody>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>some comment</td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>It’s also possible to include source code snippets; see the guides linked previously</p>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_images">9.9. Images</h3>
<div class="paragraph">
<p>Use the <code>image:</code> macro to reference images. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>image:_images/vscode.png[]</pre>
</div>
</div>
<div class="paragraph">
<p>will render as:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="_images/vscode.png" alt="vscode"></span></p>
</div>
<div class="paragraph">
<p>to make the image clickable, add in the <code>link</code> attribute:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>image:_images/vscode.png[link="_images/vscode.png"]</pre>
</div>
</div>
<div class="paragraph">
<p>will render as:</p>
</div>
<div class="paragraph">
<p><span class="image"><a class="image" href="_images/vscode.png"><img src="_images/vscode.png" alt="vscode"></a></span></p>
</div>
<div class="paragraph">
<p>to make the image clickable, add in the <code>link</code> attribute:</p>
</div>
<div class="paragraph">
<p>It’s also possible to specify the width using <code>scaledwidth</code> (for PDF/HTML) or <code>width</code> and <code>height</code> (for HTML only).</p>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_child-documents">9.10. Child Documents</h3>
<div class="paragraph">
<p>Use the <code>include:</code> macro to break up a document into multiple sections.</p>
</div>
<div class="paragraph">
<p>For example, the <a href="../../setting-up/concepts/concepts.html">concepts</a> document is broken into several files:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>concepts.adoc
_concepts_why-a-new-platform.adoc
_concepts_ci-as-a-service.adoc
_concepts_git-intro.adoc</pre>
</div>
</div>
<div class="paragraph">
<p>and so on.</p>
</div>
<div class="paragraph">
<p>These are included using:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="asciidoc">include::_concepts_why-a-new-platform.adoc[leveloffset=+1]
include::_concepts_ci-as-a-service.adoc[leveloffset=+1]
include::_concepts_git-intro.adoc[leveloffset=+1]</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>leveloffset=+1</code> means that each included file’s heading levels are automatically adjusted. The net effect is that all documents can and should use heading 1 as their top-level.</p>
</div>
<div class="paragraph">
<p>Child documents should have '_' as prefix. This ensures that they are ignored by the build; only .html and PDF files are created for the top-level parent documents.</p>
</div>
<div class="paragraph">
<p>The CI/documentation platform also supports the "Improve this doc" button, allowing any document to be edited via the TFS portal; very useful for small fixes. To make this work, it relies upon the following naming conventions:</p>
</div>
<div class="ulist">
<ul>
<li> <p>every document should have an id anchor for its level heading corresponding to its file name</p> </li>
<li> <p>every child document’s name should be an '_ followed by the name of its parent.</p> </li>
</ul>
</div>
<div class="paragraph">
<p>For example, <code>concepts.adoc</code> is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="asciidoc">[[concepts]]
= Concepts
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>while its child document <code>_concepts_why-a-new-platform.adoc</code> starts with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="asciidoc">[[_concepts_why-a-new-platform]]
= Why a new platform?
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>In general, we use '_' to separate out the logical hierarchy:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>xxx-xxx/xxx-xxx.adoc
_xxx-xxx_ppp-ppp.adoc
_xxx-xxx_qqq-qqq.adoc
_xxx-xxx_qqq-qqq_mmm-mmm.adoc
_xxx-xxx_qqq-qqq_nnn-nnn.adoc</code></pre>
</div>
</div>
<div class="paragraph">
<p>Any referenced images should be in subdirectories of the <code>_images</code> directory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>xxx-xxx/_images/.
/ppp-ppp/.
/qqq-qqq/.
/mmm-mmm
/nnn-nnn</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_metadata">9.11. Metadata</h3>
<div class="paragraph">
<p>The top-level document must include the <code>_basedir</code> attribute; this points to the parent directory <code>src/main/asciidoc</code>. This attribute is set immediately after the top-level heading.</p>
</div>
<div class="paragraph">
<p>In addition, the <code>:toc:</code> adds a table of contents.</p>
</div>
<div class="paragraph">
<p>For example, the <code>setting-up/concepts/concepts.adoc</code> file starts:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="asciidoc">[[concepts]]
= Concepts
:_basedir: ../../
:toc: right
...</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_uml">9.12. UML diagrams</h3>
<div class="paragraph">
<p>Asciidoctor includes support for the <a href="http://plantuml.com/">plantuml</a>, allowing simple UML diagrams to be easily sketched.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[plantuml,images/asciidoctor/plantuml-demo,png]
--
class Car
Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns
--</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/asciidoctor/plantuml-demo.png" alt="plantuml demo" width="369" height="193">
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_ditaa">9.13. Ditaa diagrams</h3>
<div class="paragraph">
<p>Asciidoctor includes support for the <a href="http://ditaa.sourceforge.net/">ditaa</a>, allowing boxes-and-lines diagrams to be easily sketched.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[ditaa,images/asciidoctor/ditaa-demo,png]
----
+--------+ +-------+ +-------+
| | --+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
----</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/asciidoctor/ditaa-demo.png" alt="ditaa demo" width="430" height="182">
</div>
</div>
</div>
<div class="sect2">
<h3 id="__dg_asciidoc_graphviz">9.14. Graphviz diagrams</h3>
<div class="paragraph">
<p>Asciidoctor includes support for the <a href="http://ditaa.sourceforge.net/">ditaa</a>, allowing boxes-and-lines diagrams to be easily sketched.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[graphviz,images/asciidoctor/graphviz-demo,png]
----
digraph automata_0 {
size ="8.5, 11";
node [shape = circle];
0 [ style = filled, color=lightgrey ];
2 [ shape = doublecircle ];
0 -> 2 [ label = "a " ];
0 -> 1 [ label = "other " ];
1 -> 2 [ label = "a " ];
1 -> 1 [ label = "other " ];
2 -> 2 [ label = "a " ];
2 -> 1 [ label = "other " ];
"Machine: a" [ shape = plaintext ];
}
----</pre>
</div>
</div>
<div class="paragraph">
<p>renders as:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/asciidoctor/graphviz-demo.png" alt="graphviz demo" width="269" height="301">
</div>
</div>
<div class="admonitionblock important">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
<td class="content">
<div class="paragraph">
<p>This requires graphviz to be installed and the <code>dot.exe</code> on the PATH. Alternatively, specify the location, eg using:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>:graphvizdot: c:\Program Files (x86)\Graphviz2.38\bin\dot.exe</pre>
</div>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_asciidoc-templates">10. Appendix: Asciidoc Templates</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p>This appendix lists the (IntelliJ) live templates available for <a href="../dg/dg.html#_dg_asciidoc">writing documentation</a> using Asciidoc. Instructions for installing the templates can be found <a href="../dg/dg.html#__dg_ide_intellij_live-templates">here</a>.</p>
</div>
<div class="paragraph">
<p>In the examples below the text <code>xxx</code>, <code>yyy</code>, <code>zzz</code> are correspond to template variables (ie placeholders).</p>
</div>
<div class="sect2">
<h3 id="_admonitions_callouts">10.1. Admonitions (Callouts)</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmimportant</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[IMPORTANT]
====
xxx
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock important">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
<td class="content">
<div class="paragraph">
<p>xxx</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmnote</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[NOTE]
====
xxx
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<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>xxx</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="literalblock">
<div class="content">
<pre></pre>
</div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmtip</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[TIP]
====
xxx
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
<p>xxx</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="literalblock">
<div class="content">
<pre></pre>
</div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmwarning</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[WARNING]
====
xxx
====</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<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>xxx</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_todo_notes">10.2. TODO notes</h3>
<div class="paragraph">
<p>Add as a placeholder for documentation still to be written or which is work-in-progress.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adtodo</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>NOTE: TODO</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock note">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content"> TODO </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adwip</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>NOTE: WIP - xxx</pre>
</div>
</div>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is additional explanatory text</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock note">
<table>
<tbody>
<tr>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content"> WIP - cool new feature </td>
</tr>
</tbody>
</table>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_xref_to_guides">10.3. Xref to Guides</h3>
<div class="paragraph">
<p>Cross-references (links) to the various guides</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adcgcom</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>xref:../cgcom/cgcom.adoc#xxx[ttt]</code></p>
</div>
<div class="paragraph">
<p>a hyperlink to a bookmark within the committers' guide, where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the bookmark’s anchor</p> </li>
<li> <p><code>ttt</code> is the text to display as the hyperlink</p> </li>
</ul>
</div>
<div class="paragraph">
<p>for example:</p>
</div>
<div class="paragraph">
<p><code>xref:../dg/dg.adoc#_cgcom_cutting-a-release[Cutting a release\]</code></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>addg</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../dg/dg.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the developers' guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark’s anchor * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../dg/dg.adoc#_dg_asciidoc-templates[Asciidoc templates\]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../dg/dg.html#_dg_asciidoc-templates">Asciidoc templates</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgant</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgant/rgant.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for annotations, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgant/rgant.adoc#_rgant_aaa_main[Core annotations]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgant/rgant.html#_rgant_aaa_main">Core annotations</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgcfg</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgcfg/rgcfg.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for configuration properties guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgcfg/rgcfg.html#_rgcfg_configuring-core">Configuring Core</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgcms</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgcms/rgcms.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for classes, methods and schema, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService</code>]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgcms/rgcms.html#_rgcms_classes_super_AbstractService"><code>AbstractService</code></a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgsvc</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgsvc/rgsvc.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for domain services, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest</code> bootstrapping]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgcms/rgcms.html#_rgcms_classes_AppManifest-bootstrapping"><code>AppManifest</code> bootstrapping</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgmvn</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgmvn/rgmvn.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for the maven plugin, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate goal]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgmvn/rgmvn.html#_rgmvn_validate">validate goal</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgna</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgant/rgant.adoc#_rgant-xxx[</code>@xxx`]` </p><p class="tableblock">a hyperlink to the "man page" for an annotation within the reference guide for annotations, where: </p><p class="tableblock">* <code>xxx</code> is the annotation type (eg <code>@Action</code>) </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgant/rgant.adoc#_rgant-Action[</code>@Action`]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgant/rgant.html#_rgant-Action"><code>@Action</code></a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgnt</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgant/rgant.adoc#_rgant-xxx_ttt[</code>@xxx#ttt()<code>]</code> </p><p class="tableblock">a hyperlink to the "man page" for the specific attribute (field) of an annotation within the reference guide for annotations, where: </p><p class="tableblock">* <code>xxx</code> is the annotation type (eg <code>@Action</code>) * <code>ttt</code> is the attribute (eg <code>@semantics</code>) </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgant/rgant.adoc#_rgant-Action_semantics[</code>@Action#semantics()<code>]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgant/rgant.html#_rgant-Action_semantics"><code>@Action#semantics()</code></a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgsa</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgsvc/rgsvc.adoc#_rgsvc_api_xxx[`xxx</code>]` </p><p class="tableblock">a hyperlink to the "man page" for an (API) domain service within the reference guide for domain services, where: </p><p class="tableblock">* <code>xxx</code> is the domain service (eg <code>DomainObjectContainer</code>) </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer</code>]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgsvc/rgsvc.html#_rgsvc_core-domain-api_DomainObjectContainer"><code>DomainObjectContainer</code></a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adrgss</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_xxx[`xxx</code>]` </p><p class="tableblock">a hyperlink to the "man page" for an (SPI) domain service within the reference guide for domain services, where: </p><p class="tableblock">* <code>xxx</code> is the domain service (eg <code>ContentMappingService</code>) </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_ContentMappingService[`ContentMappingService</code>]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_ContentMappingServicef"><code>ContentMappingService</code></a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adugfun</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../ugfun/ugfun.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the fundamentals users' guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark’s anchor * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../ugfun/ugfun.adoc#_ugfun_core-concepts[Core concepts]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugfun/ugfun.html#_ugfun_core-concepts">Core concepts</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adugvw</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../ugvw/ugvw.adoc#xxx[ttt]</code> </p><p class="tableblock">A hyperlink to a bookmark within the Wicket viewer guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark’s anchor * <code>ttt</code> is the text to display as the hyperlink. </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../ugvw/ugvw.adoc#_ugvw_customisation[Customisation]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugvw/ugvw.html#_ugvw_customisation">Customisation</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adugvro</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../ugvro/ugvro.adoc#xxx[ttt]</code> </p><p class="tableblock">A hyperlink to a bookmark within the Restful Objects viewer guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark’s anchor * <code>ttt</code> is the text to display as the hyperlink. </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../ugvro/ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugvro/ugvro.html#_ugvro_ro-spec">RestfulObjects specification</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adugsec</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../ugsec/ugsec.adoc#xxx[ttt]</code> </p><p class="tableblock">A hyperlink to a bookmark within the Secrurity guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark’s anchor * <code>ttt</code> is the text to display as the hyperlink. </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips_shiro-caching[Caching and other Shiro Features]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugsec/ugsec.html#_ugsec_hints-and-tips_shiro-caching">Caching and other Shiro Features</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adugtst</code></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:../ugtst/ugtst.adoc#xxx[ttt]</code> </p><p class="tableblock">A hyperlink to a bookmark within the Testing guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark’s anchor * <code>ttt</code> is the text to display as the hyperlink. </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:../ugtst/ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="../ugtst/ugtst.html#_ugtst_bdd-spec-support">BDD Spec Support</a></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>adugbtb</code></p>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_source_code">10.4. Source code</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcjava</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[source,java]
----
xxx
----</pre>
</div>
</div>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the source code snippet.</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Foo</span> {
...
}</code></pre>
</div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcjavac</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>adsrcjava</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcjavascript</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[source,javascript]
----
xxx
----</pre>
</div>
</div>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the source code snippet.</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript"><span class="predefined">$</span>(document).ready(<span class="keyword">function</span>() {
...
});</code></pre>
</div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcjavascriptc</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>adsrcjavascript</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcother</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[source,nnn]
----
xxx
---</pre>
</div>
</div>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>nnn</code> is the programming language</p> </li>
<li> <p><code>xxx</code> is the source code snippet.</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcotherc</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>adsrcother</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcxml</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="literalblock">
<div class="content">
<pre>[source,javascript]
----
xxx
----</pre>
</div>
</div>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the source code snippet.</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><html></span>
<span class="tag"><title></span>
hello world!
<span class="tag"></title></span>
<span class="tag"></html></span></code></pre>
</div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adsrcxmlc</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>adsrcxml</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_images">10.5. Images</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adimgfile</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>image:images/xxx/yyy.png[width="WWWpx",link="images/xxx/yyy.png"]</code></p>
</div>
<div class="paragraph">
<p>embeds specified image, where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the subdirectory under the <code>images/</code> directory</p> </li>
<li> <p><code>yyy</code> is the image</p> </li>
<li> <p><code>WWW</code> is the width, in pixels.</p> </li>
</ul>
</div>
<div class="paragraph">
<p>for example:</p>
</div>
<div class="paragraph">
<p><code>image:images/layouts/estatio-Lease.png[width="300px",link="images/layouts/estatio-Lease.png"]</code></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><span class="image"><a class="image" href="images/layouts/estatio-Lease.png"><img src="images/layouts/estatio-Lease.png" alt="estatio Lease" width="300px"></a></span></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adimgfilec</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>adimgfile</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adimgurl</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>image:xxx[width="WWWpx",link="xxx"]</code></p>
</div>
<div class="paragraph">
<p>embeds image from specified URL, where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the URL to the image</p> </li>
<li> <p><code>WWW</code> is the width, in pixels.</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adimgurlc</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>adimgurl</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_youtube_screencasts">10.6. YouTube (screencasts)</h3>
<div class="paragraph">
<p>Embedded youtube screencasts. (Don’t use these in guides, as they cannot be rendered as PDF).</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adyoutube</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>video:xxx[youtube,width="WWWpx",height="HHHpx"]</code></p>
</div>
<div class="paragraph">
<p>where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the youtube reference</p> </li>
<li> <p><code>WWW</code> is the width, in pixels</p> </li>
<li> <p><code>HHH</code> is the height, in pixels</p> </li>
</ul>
</div>
<div class="paragraph">
<p>for example:</p>
</div>
<div class="paragraph">
<p><code>video::bj8735nBRR4[youtube,width="210px",height="118px"]</code></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="videoblock">
<div class="content">
<iframe width="210px" height="118px" src="https://www.youtube.com/embed/bj8735nBRR4?rel=0" frameborder="0" allowfullscreen></iframe>
</div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adyoutubec</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>as for <code>youtube</code>, but with a caption above</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_tables">10.7. Tables</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adtbl3</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Table with 3 columns, 3 rows.</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_misc">10.8. Misc.</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
<col style="width: 57.1428%;">
<col style="width: 28.5715%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Abbrev.</th>
<th class="tableblock halign-left valign-top">Produces</th>
<th class="tableblock halign-left valign-top">Example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adai</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>Apache Isis</code><br></p>
</div>
<div class="paragraph">
<p>That is, the literal text "Apache Isis".</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p>Apache Isis</p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adlink</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>link:xxx[ttt]</code></p>
</div>
<div class="paragraph">
<p>, where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is</p> </li>
<li> <p><code>ttt</code> is the text to display as the hyperlink</p> </li>
</ul>
</div>
<div class="paragraph">
<p>for example:</p>
</div>
<div class="paragraph">
<p><code>link:http://isis.apache.org[Apache Isis website]</code></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><a href="http://isis.apache.org">Apache Isis website</a></p>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adanchany</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>= anchor:[xxx]</code></p>
</div>
<div class="paragraph">
<p>defines an inline anchor to any heading, where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the anchor text.</p> </li>
</ul>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="paragraph">
<p><code>= anchor:[_ugfun_i18n] Internationalization</code></p>
</div>
<div class="paragraph">
<p>An alternative (more commonly used in our documentation) is to use the <code>[[…]]</code> directly above the heading:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[[_ugfun_i18n]]
= Internationalization</pre>
</div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adxrefany</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>\xref:[xxx]</code></p>
</div>
<div class="paragraph">
<p>cross-reference to any document/anchor, where:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>xxx</code> is the fully qualified document with optional anchor</p> </li>
</ul>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adfootnote</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><code>footnote:[xxx]</code></p>
</div>
<div class="paragraph">
<p>defines a footnote</p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
<p><sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnote_1" title="View footnote.">1</a>]</sup></p>
</div>
<div id="footnotes">
<hr>
<div class="footnote" id="_footnote_1">
<a href="#_footnoteref_1">1</a>. this is a footnote
</div>
</div>
</div></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_project-lombok">11. Appendix: Project Lombok</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<div class="paragraph">
<p><a href="https://projectlombok.org/">Project Lombok</a> is an open source project to reduce the amount of boilerplate in your code.</p>
</div>
<div class="paragraph">
<p>For example, rather than write:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">private</span> <span class="predefined-type">String</span> name;
<span class="directive">public</span> <span class="predefined-type">String</span> getName() {
<span class="keyword">return</span> name;
}
<span class="directive">public</span> <span class="type">void</span> setName(<span class="predefined-type">String</span> name) {
<span class="local-variable">this</span>.name = name;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>you can instead write simply:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
<span class="directive">private</span> <span class="predefined-type">String</span> name;</code></pre>
</div>
</div>
<div class="paragraph">
<p>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 <a href="../dg/dg.html#__dg_ide_intellij_other-settings-compiler">here</a> for details of setting up in IntelliJ (Eclipse has very similar support).</p>
</div>
<div class="paragraph">
<p>Apache Isis supports <a href="https://projectlombok.org/">Project Lombok</a>, in that the annotations that would normally be placed on the getter (namely <a href="../rgant/rgant.html#_rgant-Property"><code>Property</code></a>, <a href="../rgant/rgant.html#_rgant-PropertyLayout"><code>@PropertyLayout</code></a>, <a href="../rgant/rgant.html#_rgant-Collection"><code>@Collection</code></a>, <a href="../rgant/rgant.html#_rgant-CollectionLayout"><code>@CollectionLayout</code></a> and <a href="../rgant/rgant.html#_rgant-MemberOrder"><code>@MemberOrder</code></a>) can be placed on the field instead.</p>
</div>
<div class="paragraph">
<p>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 <a href="https://projectlombok.org/download.html">Lombok download page</a> for more information.</p>
</div>
<div class="sect2">
<h3 id="_future_thoughts">11.1. Future thoughts</h3>
<div class="paragraph">
<p>In the future we might extend/fork Lombok so that it understands Isis' own annotations (ie <a href="../rgant/rgant.html#_rgant-Property"><code>@Property</code></a> and <a href="../rgant/rgant.html#_rgant-Collection"><code>@Collection</code></a>) rather than Lombok’s own <code>@Getter</code> and `@Setter.</p>
</div>
<div class="paragraph">
<p>It might also be possible to use Lombok to generate the domain event classes for each member.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dg_agilej">12. Appendix: AgileJ</h2>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
<ul class="dropdown-menu">
<li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
<li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
<li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
<li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
</ul>
</div>
<div class="sectionbody">
<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; AgileJ Structure Views is not affiliated to Apache Software Foundation in any way. AgileJ has however provided a complimentary copy of its software to Apache Isis committers.</p>
</div> </td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p><a href="http://www.agilej.com/">AgileJ Structure Views</a> is a commercial product to reverse engineer and visualize Java classes from source code.</p>
</div>
<div class="paragraph">
<p>The key to using the tool is in developing a suitable filter script, a DSL. You can use the following script as a starting point for visualizing Apache Isis domain models:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="AgileJ">// use CTRL+SPACE for completion suggestions
hide all fields
hide setter methods
hide private methods
hide methods named compareTo
hide methods named toString
hide methods named inject*
hide methods named disable*
hide methods named default*
hide methods named hide*
hide methods named autoComplete*
hide methods named choices*
hide methods named title
hide methods named iconName
hide methods named validate*
hide methods named modify*
hide protected methods
hide types annotated as DomainService
hide types named Constants
hide types named InvoicingInterval
hide enums
hide constructors
hide inner types named *Event
hide inner types named *Functions
hide inner types named *Predicates
show getter methods in green
show methods annotated as Programmatic in orange
show methods annotated as Action in largest
hide dependency lines
hide call lines
hide method lines</code></pre>
</div>
</div>
<div class="paragraph">
<p>For more information on AgileJ, see Paul Wells' 8-part tutorial series on Youtube; the first can be found <a href="https://www.youtube.com/watch?v=YrZQ7lMSsH0">here</a> (view the "show more" comments to click through to other parts).</p>
</div>
</div>
</div>
</div>
</div>
<div class="hidden-xs hidden-sm hidden-md col-lg-3">
<nav id="toc" data-spy="affix" data-toggle="toc"></nav>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<div class="row">
<p class="text-center small text-muted"> Copyright © 2010~2017 The Apache Software Foundation, licensed under the Apache License, v2.0. <br> Apache, the Apache feather logo, Apache Isis, and the Apache Isis project logo are all trademarks of The Apache Software Foundation. </p>
</div>
</div>
</footer>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="../../js/bootstrap/3.3.7/bootstrap.min.js"></script>
<script src="../../js/bootstrap-toc/0.4.1/bootstrap-toc.min.js"></script>
<script src="../../js/slick/1.5.0/slick.min.js"></script>
<script src="../../js/elasticlunr/elasticlunr.min.js"></script>
<script src="../../js/sticky-header/sticky-header.js"></script>
<script src="../../js/search-panel/search-panel.js"></script>
<script src="../../js/header-link/header-link.js"></script>
<script src="../../js/toc-scroll/toc-scroll.js"></script>
</body>
</html>