You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/11/26 20:27:34 UTC
isis-site git commit: ISIS-1243: renamed troubleshooting to faq,
added some questions
Repository: isis-site
Updated Branches:
refs/heads/asf-site b28deef4c -> 9862c26d4
ISIS-1243: renamed troubleshooting to faq, added some questions
Project: http://git-wip-us.apache.org/repos/asf/isis-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis-site/commit/9862c26d
Tree: http://git-wip-us.apache.org/repos/asf/isis-site/tree/9862c26d
Diff: http://git-wip-us.apache.org/repos/asf/isis-site/diff/9862c26d
Branch: refs/heads/asf-site
Commit: 9862c26d459053cd88791dd9b972d277269beb47
Parents: b28deef
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Nov 26 16:33:07 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Nov 26 16:33:07 2015 +0000
----------------------------------------------------------------------
content/guides/cg.html | 87 ++++++++++++++++++--
content/guides/rg.html | 8 +-
content/guides/ug.html | 188 ++++++++++++++++++++++++++++++++------------
3 files changed, 224 insertions(+), 59 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis-site/blob/9862c26d/content/guides/cg.html
----------------------------------------------------------------------
diff --git a/content/guides/cg.html b/content/guides/cg.html
index 1bf8214..983cebd 100644
--- a/content/guides/cg.html
+++ b/content/guides/cg.html
@@ -553,9 +553,6 @@ table.CodeRay td.code>pre{padding:0}
</div>
<div class="sect2">
<h3 id="_cg_ide_intellij">2.1. Developing using IntelliJ IDEA</h3>
-<div class="paragraph">
-<p>This section describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.</p>
-</div>
<div class="admonitionblock note">
<table>
<tr>
@@ -564,16 +561,20 @@ table.CodeRay td.code>pre{padding:0}
</td>
<td class="content">
<div class="paragraph">
-<p>This document relates to IntelliJ Community Edition 14.1.x, with screenshots taken for Windows.</p>
+<p>This material does not constitute an endorsement; JetBrains is not affiliated to Apache Software Foundation in any way.</p>
</div>
</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>This section describes how to install and setup JetBrains' IntelliJ IDEA, then how to import an application into IntelliJ and run it.</p>
+</div>
<div class="sect3">
<h4 id="_installing_and_setting_up">2.1.1. Installing and Setting up</h4>
<div class="paragraph">
-<p>This section covers installation and setup.</p>
+<p>This section covers installation and setup. These notes relates to IntelliJ Community Edition 14.1.x, with
+screenshots taken for Windows.</p>
</div>
<div class="sect4">
<h5 id="_download_and_install">Download and Install</h5>
@@ -1393,6 +1394,20 @@ non-commercial free license (though note this comes with some usage conditions).
</div>
<div class="sect2">
<h3 id="_cg_ide_eclipse">2.2. Developing using Eclipse</h3>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>This material does not constitute an endorsement; Eclipse foundation is not affiliated to Apache Software Foundation in any way.</p>
+</div>
+</td>
+</tr>
+</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>
@@ -1650,6 +1665,67 @@ rather than Lombok’s own <code>@Getter</code> and `@Setter.</p>
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_cg_ide_agilej">2.4. AgileJ</h3>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>This material does not constitute an endorsement; AgileJ Structure Views is not affiliated to Apache Software Foundation in any way.</p>
+</div>
+</td>
+</tr>
+</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 class="sect1">
@@ -8288,6 +8364,7 @@ xxx<br>
<li><a href="#_future_thoughts">2.3.1. Future thoughts</a></li>
</ul>
</li>
+<li><a href="#_cg_ide_agilej">2.4. AgileJ</a></li>
</ul>
</li>
<li><a href="#_cg_ide-templates">3. Code and File Templates</a>
http://git-wip-us.apache.org/repos/asf/isis-site/blob/9862c26d/content/guides/rg.html
----------------------------------------------------------------------
diff --git a/content/guides/rg.html b/content/guides/rg.html
index f9105f3..93e38bf 100644
--- a/content/guides/rg.html
+++ b/content/guides/rg.html
@@ -22627,7 +22627,7 @@ TODO
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+TODO - the <code>org.apache.isis.applib.value.Blob</code> class.
</td>
</tr>
</table>
@@ -22642,7 +22642,7 @@ TODO
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+TODO - the <code>org.apache.isis.applib.value.Clob</code> class.
</td>
</tr>
</table>
@@ -22657,7 +22657,7 @@ TODO
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+TODO - the <code>org.apache.isis.applib.value.Color</code> class.
</td>
</tr>
</table>
@@ -22672,7 +22672,7 @@ TODO
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+TODO - the <code>org.apache.isis.applib.value.Money</code> class.
</td>
</tr>
</table>
http://git-wip-us.apache.org/repos/asf/isis-site/blob/9862c26d/content/guides/ug.html
----------------------------------------------------------------------
diff --git a/content/guides/ug.html b/content/guides/ug.html
index da2c159..1601746 100644
--- a/content/guides/ug.html
+++ b/content/guides/ug.html
@@ -15176,76 +15176,176 @@ public WebRequest newWebRequest(HttpServletRequest servletRequest, String filter
</div>
</div>
<div class="sect1">
-<h2 id="_ug_troubleshooting">13. Troubleshooting</h2>
+<h2 id="_ug_faqs">13. FAQs</h2>
<div class="sectionbody">
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>This chapter has FAQs (with solutions) for problems we’ve encountered ourselves or have been raised on the
+Apache Isis mailing lists.</p>
+</div>
+<div class="sect2">
+<h3 id="_ug_faqs_enabling-logging">13.1. Enabling Logging</h3>
+<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="#_ug_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="_ug_troubleshooting_faqs">13.2. (Subtype) entity not fully populated</h3>
+<div class="paragraph">
+<p>ref: <a href="http://markmail.org/message/ovgai56uqgfgnrx7">mailing list thread</a></p>
+</div>
+<div class="paragraph">
+<p>If it seems that Apache Isis (or rather DataNucleus) isn’t fully populating domain entities (ie leaving some properties
+as <code>null</code>), then check that your actions are not accessing the fields directly. Use getters instead. that is:</p>
+</div>
+<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
-TODO
+<div class="paragraph">
+<p>Properties of domain entities should always be accessed using getters. The only code that should access to fields
+should be the getters themselves.</p>
+</div>
</td>
</tr>
</table>
</div>
-<div class="sect2">
-<h3 id="_logging_2">13.1. Logging</h3>
-
+<div class="paragraph">
+<p>Why so? Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the
+field is being requested. This is the purpose of the enhancement phase: the bytecode of the original getter method is
+actually wrapped in code that does the lazy loading checking. But hitting the field directly means that the lazy
+loading code does not run.</p>
</div>
-<div class="sect2">
-<h3 id="_ug_troubleshooting_enabling-logging">13.2. Enabling Logging</h3>
<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>
+<p>This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work. But that will be
+because the field has been populated already, for whatever reason.</p>
</div>
-<div class="sect3">
-<h4 id="_in_apache_isis">13.2.1. In Apache Isis</h4>
<div class="paragraph">
-<p>Modify <code>WEB-INF/logging.properties</code> (a log4j config file)</p>
+<p>One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance
+strategy of <code>NEW_TABLE</code>, eg:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable
+<span class="annotation">@javax</span>.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SupertypeEntity</span> {
+ ...
+}</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_in_datanucleus">13.2.2. In DataNucleus</h4>
<div class="paragraph">
-<p>As per the <a href="http://www.datanucleus.org/products/accessplatform/logging.html">DN logging page</a></p>
+<p>and then:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable
+<span class="annotation">@javax</span>.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SubtypeEntity</span> <span class="directive">extends</span> SupertypeEntity {
+ ...
+}</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_in_the_jdbc_driver">13.2.3. In the JDBC Driver</h4>
<div class="paragraph">
-<p>Configure log4jdbc 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>).</p>
+<p>This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key
+(also primary key) of the subtype table (sometimes called "table per type" strategy). This means that DataNucleus
+might retrieve data from only the supertype table, and the lazily load the subtype fields only as required. This is
+preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.</p>
</div>
<div class="paragraph">
-<p>There are examples of both in the <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
+<p>On the other hand, if the <code>SUPERCLASS_TABLE</code> strategy (aka "table per hierarchy" or roll-up) or the <code>SUBCLASS_TABLE</code>
+strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data
+for any given instance from a single table.</p>
</div>
+<div class="paragraph">
+<p>Final note: references to other objects (either scalar references or in collections) in particular require that getters
+rather than fields to be used to obtain them: it’s hopefully obvious that DataNucleus (like all ORMs) should not and
+will not resolve such references (otherwise, where to stop…​ and the whole database would be loaded into memory).</p>
</div>
-<div class="sect3">
-<h4 id="_in_the_database">13.2.4. In the Database</h4>
-<div class="sect4">
-<h5 id="_hsqldb_logging">HSQLDB Logging</h5>
<div class="paragraph">
-<p>Add <code>;sqllog=3</code> to the end of the JDBC URL.</p>
+<p>In summary, there’s just one rule: <strong>always use the getters, never the fields</strong>.</p>
</div>
</div>
-<div class="sect4">
-<h5 id="_postgresql_logging">PostgreSQL Logging</h5>
+<div class="sect2">
+<h3 id="_ug_faqs_restful-image-property">13.3. How parse image properties from Restful Objects?</h3>
<div class="paragraph">
-<p>In <code>postgresql\9.2\data\postgresql.conf</code>:</p>
+<p>ref: <a href="http://markmail.org/message/4kcu7sml4ufdsah3">mailing list thread</a></p>
</div>
<div class="paragraph">
-<p>Will then log to <code>postgresql\9.2\data\pg_log</code> directory.</p>
+<p>The RO viewer returns the image as a string, in the form:</p>
</div>
-<div class="paragraph">
-<p>Note that you must restart the service for this to be picked up.</p>
+<div class="literalblock">
+<div class="content">
+<pre>"Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/ ...."</pre>
</div>
</div>
-<div class="sect4">
-<h5 id="_ms_sql_server_logging">MS SQL Server Logging</h5>
<div class="paragraph">
-<p>Use the excellent SQL Profiler tool.</p>
+<p>This is in the form:</p>
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>(filename):(mime type):(binary data in base64)</pre>
</div>
</div>
+<div class="paragraph">
+<p>This is basically the <a href="rg.html#_rg_classes_value-types_manpage-Blob"><code>Blob</code></a> value type, in string form.</p>
+</div>
+<div class="paragraph">
+<p>To use, split the parts then format the mime type and base64 data correctly before using as source in an <code><img></code> tag.</p>
</div>
</div>
</div>
@@ -16046,23 +16146,11 @@ TODO
<li><a href="#_ug_extending_restfulobjects-viewer">12.3. Restful Objects viewer</a></li>
</ul>
</li>
-<li><a href="#_ug_troubleshooting">13. Troubleshooting</a>
+<li><a href="#_ug_faqs">13. FAQs</a>
<ul class="sectlevel2">
-<li><a href="#_logging_2">13.1. Logging</a></li>
-<li><a href="#_ug_troubleshooting_enabling-logging">13.2. Enabling Logging</a>
-<ul class="sectlevel3">
-<li><a href="#_in_apache_isis">13.2.1. In Apache Isis</a></li>
-<li><a href="#_in_datanucleus">13.2.2. In DataNucleus</a></li>
-<li><a href="#_in_the_jdbc_driver">13.2.3. In the JDBC Driver</a></li>
-<li><a href="#_in_the_database">13.2.4. In the Database</a>
-<ul class="sectlevel4">
-<li><a href="#_hsqldb_logging">HSQLDB Logging</a></li>
-<li><a href="#_postgresql_logging">PostgreSQL Logging</a></li>
-<li><a href="#_ms_sql_server_logging">MS SQL Server Logging</a></li>
-</ul>
-</li>
-</ul>
-</li>
+<li><a href="#_ug_faqs_enabling-logging">13.1. Enabling Logging</a></li>
+<li><a href="#_ug_troubleshooting_faqs">13.2. (Subtype) entity not fully populated</a></li>
+<li><a href="#_ug_faqs_restful-image-property">13.3. How parse image properties from Restful Objects?</a></li>
</ul>
</li>
</ul>