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/07/08 09:25:25 UTC
isis-site git commit: ISIS-1052: added how-to for persisted title
Repository: isis-site
Updated Branches:
refs/heads/asf-site 26fb59fcd -> e5e5c83bf
ISIS-1052: added how-to for persisted title
Project: http://git-wip-us.apache.org/repos/asf/isis-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis-site/commit/e5e5c83b
Tree: http://git-wip-us.apache.org/repos/asf/isis-site/tree/e5e5c83b
Diff: http://git-wip-us.apache.org/repos/asf/isis-site/diff/e5e5c83b
Branch: refs/heads/asf-site
Commit: e5e5c83bf68a7031629d68252fe157e8c4fdee28
Parents: 26fb59f
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Jul 8 08:18:56 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Jul 8 08:18:56 2015 +0100
----------------------------------------------------------------------
content/guides/rg.html | 19 +++--
content/guides/ug.html | 165 ++++++++++++++++++++++++++++++--------------
2 files changed, 127 insertions(+), 57 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis-site/blob/e5e5c83b/content/guides/rg.html
----------------------------------------------------------------------
diff --git a/content/guides/rg.html b/content/guides/rg.html
index bb089ce..b7daf9b 100644
--- a/content/guides/rg.html
+++ b/content/guides/rg.html
@@ -11568,7 +11568,8 @@ RemoveFrom…​()</code></a></p></td>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@RequestScoped</span> <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
<span class="directive">public</span> <span class="type">class</span> <span class="class">ObjectChangedListenerService</span>
<span class="directive">implements</span> javax.jdo.listener.StoreLifecycleListener { <i class="conum" data-value="1"></i><b>(1)</b>
<span class="annotation">@Programmatic</span>
@@ -11581,9 +11582,8 @@ RemoveFrom…​()</code></a></p></td>
<span class="directive">public</span> <span class="type">void</span> tidyUp() {
getPmFactory().removeInstanceLifecycleListener(<span class="local-variable">this</span>);
}
- <span class="directive">private</span> PersistenceManagerFactory getPmFactory() {
- <span class="keyword">return</span> jdoSupport.getPersistenceManager()
- .getPersistenceManagerFactory(); <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="directive">private</span> PersistenceManager getPersistenceManager() {
+ <span class="keyword">return</span> jdoSupport.getPersistenceManager(); <i class="conum" data-value="3"></i><b>(3)</b>
}
<span class="annotation">@Programmatic</span>
<span class="directive">public</span> <span class="type">void</span> preStore (InstanceLifecycleEvent event) { ... }
@@ -11598,14 +11598,21 @@ RemoveFrom…​()</code></a></p></td>
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>implement whichever callback lifecycle listeners are of interest</td>
+<td>must be <code>@RequestScoped</code> because we register on the <code>PersistenceManager</code>, which is different for each request.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>register on the factory so set up for every subsequent session.</td>
+<td>implement whichever callback lifecycle listeners are of interest</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>use the injected <a href="#_rg_services-api_manpage-IsisJdoSupport"><code>IsisJdoSupport</code></a> service to obtain the <code>PersistenceManager</code>.</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>Note that it isn’t possible to register on the <code>PersistenceManagerFactory</code> because listeners cannot be attached once a persistence session has been created (which it will have been when the service’s <code>@PostConstruct</code> method is called).</p>
+</div>
</div>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/isis-site/blob/e5e5c83b/content/guides/ug.html
----------------------------------------------------------------------
diff --git a/content/guides/ug.html b/content/guides/ug.html
index 4f2c422..1ef2e2d 100644
--- a/content/guides/ug.html
+++ b/content/guides/ug.html
@@ -983,14 +983,14 @@ TODO - behaviourally Complete vs Contributions
</div>
<div class="sect4">
<h5 id="_testable">Testable</h5>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -4565,14 +4565,14 @@ mvn clean install</code></pre>
</div>
<div class="sect3">
<h4 id="_ug_how-tos_class-structure_class-definition">4.1.1. Class Definition</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -4617,14 +4617,14 @@ TODO
</div>
<div class="sect4">
<h5 id="_value_vs_reference_types">Value vs Reference Types</h5>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -4961,14 +4961,14 @@ TODO
</div>
<div class="sect3">
<h4 id="_ug_how-tos_class-structure_collections">4.1.3. Collections</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -5177,14 +5177,14 @@ public, and has a single parameter of the correct type.</p>
</div>
<div class="sect3">
<h4 id="_ug_how-tos_class-structure_properties-vs-parameters">4.1.7. Properties vs Parameters</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -5241,14 +5241,14 @@ WIP
</div>
<div class="sect3">
<h4 id="_ug_how-tos_class-structure_ignoring-methods">4.1.8. Ignoring Methods</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -5625,14 +5625,14 @@ TODO - screenshot here
</div>
<div class="sect4">
<h5 id="_per_action">Per action</h5>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - <a href="rg.html#_rg_annotations_manpage-ActionLayout_cssClass"><code>@ActionLayout#cssClass()</code></a> and <a href="rg.html#_rg_annotations_manpage-ActionLayout_cssClassFa"><code>@ActionLayout#cssClassFa()</code></a>
+TODO - <a href="rg.html#_rg_annotations_manpage-ActionLayout_cssClass"><code>@ActionLayout#cssClass()</code></a> and <a href="rg.html#_rg_annotations_manpage-ActionLayout_cssClassFa"><code>@ActionLayout#cssClassFa()</code></a>
</td>
</tr>
</table>
@@ -5785,14 +5785,14 @@ isis.services = employee.Employees,\
</div>
<div class="sect3">
<h4 id="_contributions_2">4.3.3. Contributions</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - just xref <a href="#_ug_how-tos_contributed-members">contributed members</a> section.
+TODO - just xref <a href="#_ug_how-tos_contributed-members">contributed members</a> section.
</td>
</tr>
</table>
@@ -5800,14 +5800,14 @@ WIP - just xref <a href="#_ug_how-tos_contributed-members">contributed members</
</div>
<div class="sect3">
<h4 id="_menu_items">4.3.4. Menu items</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - update to new annotations, including @DomainService(nature=…​)
+TODO - update to new annotations, including @DomainService(nature=…​)
</td>
</tr>
</table>
@@ -5843,14 +5843,14 @@ WIP - update to new annotations, including @DomainService(nature=…​)
</div>
<div class="sect3">
<h4 id="_menus">4.3.5. Menus</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - update to new annotations, including @DomainService(nature=…​)
+TODO - update to new annotations, including @DomainService(nature=…​)
</td>
</tr>
</table>
@@ -6090,14 +6090,14 @@ TODO
</div>
<div class="sect2">
<h3 id="_ug_how-tos_contributed-members">4.6. Contributed Members</h3>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - generalize to discussion on contributed collections/properties; update to new annotations
+TODO - generalize to discussion on contributed collections/properties; update to new annotations
</td>
</tr>
</table>
@@ -6380,14 +6380,14 @@ TODO
</div>
<div class="sect3">
<h4 id="_derived_collection">4.8.2. Derived Collection</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -6456,14 +6456,14 @@ TODO
</div>
<div class="sect3">
<h4 id="_for_properties">4.9.1. For Properties</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -6516,14 +6516,14 @@ TODO - <a href="rg.html#_rg_methods_prefixes_manpage-default"><code>defaultR
</div>
<div class="sect3">
<h4 id="_for_action_parameters">4.9.2. For Action Parameters</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -6591,14 +6591,14 @@ TODO - <a href="rg.html#_rg_methods_prefixes_manpage-default"><code>defaultR
</div>
<div class="sect3">
<h4 id="_for_both_properties_and_action_parameters">4.9.3. For both Properties and Action Parameters</h4>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP
+TODO
</td>
</tr>
</table>
@@ -6626,6 +6626,68 @@ TODO - <a href="rg.html#_rg_annotations_manpage-DomainObject_bounded"><code>@Dom
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_ug_how-tos_persisted-title">4.10. Persisted Title</h3>
+<div class="paragraph">
+<p>Normally the title of an object is not persisted to the database, rather it is recomputed automatically from underlying properties. On occasion though you might want the title to also be persisted; either to make things easier for the DBA, or for an integration scenario, or some other purpose.</p>
+</div>
+<div class="paragraph">
+<p>We can implement this feature by leveraging the <a href="rg.html#_rg_methods_lifecycle_jdo-api">JDO lifecycle</a>. In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a <code>ObjectWithPersistedTitle</code> interface:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">ObjectWithPersistedTitle</span> {
+ <span class="annotation">@PropertyLayout</span>(hidden = Where.EVERYWHERE) <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="predefined-type">String</span> getTitle();
+ <span class="type">void</span> setTitle(<span class="directive">final</span> <span class="predefined-type">String</span> title);
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>we don’t want to expose this in the UI because the title is already prominently displayed.</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>We can then define a domain service that leverage this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@RequestScoped</span>
+<span class="annotation">@DomainService</span>(nature = NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">TitlingService</span> {
+ <span class="annotation">@PostConstruct</span>
+ <span class="directive">public</span> <span class="type">void</span> init() {
+ isisJdoSupport.getJdoPersistenceManager().addInstanceLifecycleListener(
+ <span class="keyword">new</span> StoreLifecycleListener() {
+ <span class="annotation">@Override</span>
+ <span class="directive">public</span> <span class="type">void</span> preStore(<span class="directive">final</span> InstanceLifecycleEvent event) {
+ <span class="directive">final</span> <span class="predefined-type">Object</span> persistentInstance = event.getPersistentInstance();
+ <span class="keyword">if</span>(persistentInstance <span class="keyword">instanceof</span> ObjectWithPersistedTitle) {
+ <span class="directive">final</span> ObjectWithPersistedTitle objectWithPersistedTitle =
+ (ObjectWithPersistedTitle) persistentInstance;
+ objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
+ }
+ }
+ <span class="annotation">@Override</span>
+ <span class="directive">public</span> <span class="type">void</span> postStore(<span class="directive">final</span> InstanceLifecycleEvent event) {
+ }
+ }, <span class="predefined-constant">null</span>);
+ }
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> IsisJdoSupport isisJdoSupport;
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> DomainObjectContainer container;
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The above is probably the easiest and most straightforward design. One could imagine other designs where the persisted title is stored elsewhere. It could even be stored off into an <a href="http://lucene.apache.org/">Apache Lucene</a> (or similar) database to allow for free-text searches.</p>
+</div>
+</div>
</div>
</div>
<div class="sect1">
@@ -7160,14 +7222,14 @@ TODO - <a href="rg.html#_rg_annotations_manpage-Action_invokeOn"><code>@Action#i
</div>
<div class="sect2">
<h3 id="_ug_more-advanced_view-models">5.4. View Models</h3>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - <a href="rg.html#_rg_annotations_manpage-ViewModel"><code>@ViewModel</code></a>, <a href="rg.html#_rg_classes_super_manpage-AbstractViewModel"><code>AbstractViewModel</code></a>, <a href="rg.html#_rg_annotations_manpage-DomainObject_nature"><code>@DomainObject#nature()</code></a>
+TODO - <a href="rg.html#_rg_annotations_manpage-ViewModel"><code>@ViewModel</code></a>, <a href="rg.html#_rg_classes_super_manpage-AbstractViewModel"><code>AbstractViewModel</code></a>, <a href="rg.html#_rg_annotations_manpage-DomainObject_nature"><code>@DomainObject#nature()</code></a>
</td>
</tr>
</table>
@@ -7962,14 +8024,14 @@ TODO
</div>
<div class="sect4">
<h5 id="_persistence_concerns">Persistence Concerns</h5>
-<div class="admonitionblock important">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-WIP - easiest to simply store using DataNucleus' support for collections, marked as <a href="rg.html#_rg_annotations_manpage-Programmatic"><code>@Programmatic</code></a> so that it is ignored by Apache Isis. Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
+TODO - easiest to simply store using DataNucleus' support for collections, marked as <a href="rg.html#_rg_annotations_manpage-Programmatic"><code>@Programmatic</code></a> so that it is ignored by Apache Isis. Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
</td>
</tr>
</table>
@@ -17579,6 +17641,7 @@ TODO
</li>
</ul>
</li>
+<li><a href="#_ug_how-tos_persisted-title">4.10. Persisted Title</a></li>
</ul>
</li>
<li><a href="#_ug_more-advanced">5. More Advanced Techniques</a>