content/versions/1.13.2.1/guides/rgcms.html

<!doctype html> <html class="no-js" lang="en"> <head> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1.0"/> <title>Classes, Methods and Schema</title>   <meta http-equiv="cache-control" content="no-cache" /> <meta http-equiv="pragma" content="no-cache" /> <meta http-equiv="expires" content="-1" />  <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet" /> <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script> <link href="../css/asciidoctor/colony.css" rel="stylesheet"> <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet"> <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet" />  <style type="text/css"> pre code { background-color: inherit; border-style: none; } pre code > span:first-child { margin-left: -5px; } <style>  <style> .github-fork-ribbon-wrapper.right { position: fixed; } .github-fork-ribbon { background: #090; } .github-fork-ribbon a:hover { background:#0D0; color:#fff; font-size: 1.1em; } </style> <style> @media only screen and (min-width: 40.063em) { .top-bar { .contain-to-grid .top-bar { max-width: 80rem; } } } .row { max-width: 80rem; } </style> <style> .extended-quote, .extended-quote-first { margin-left: 40px; margin-right: 40px; font-style: italic; } .extended-quote-attribution { text-align: right; margin-right: 100px; color: #10B061; } .extended-quote-first:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #003b6b; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); } </style> <style> body { position: relative; } *:not(pre) a > code { color: #210DDC; } *:not(pre) > code { background-color: inherit; border: none; font-weight: normal; } body div#toc li, body div#toc2 li { list-style-type: none; } div#doc-content { margin-top: 30px; } div.documentation-page table.frame-all { border-left: none; border-right: none; } body div#toc li.active-region:before, body div#toc2 li.active-region:before { content: "\00BB \0020"; margin-left: -12px; } body div#toc li a.active, body div#toc2 li a.active { color: red; } body div#toc.toc, body div#toc.toc2 { position: fixed; left: auto; padding-top: 60px; z-index: auto; background-color: white; border-left-color: #eee; border-left-style: solid; border-right: none; min-height: 2000px; } </style> <style> @media only screen and (min-width: 768px) { #toc.toc2 ul ul { margin-left: -10px; } } body div#toc .tocify-subheader ul { margin-bottom: 0px; } body div#toc .tocify-subheader li { font-size: 14px; } .tocify li.tocify-item, .tocify ul.tocify-item { line-height: 24px; } body div#toc li.tocify-item.active:before, body div#toc2 li.tocify-item.active:before { content: "\00BB \0020"; margin-left: -12px; } body div#toc li.tocify-item.active a, body div#toc2 li.tocify-item.active a { color: red; } </style> <style> footer { margin-top: 1000px; } </style> <style> /* overriding colony.css stylesheet */ .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { /*padding: 1.25em 1.5625em 1.125em 1.5625em;*/ padding: 0.3em 0.6em 0.25em 0.6em; } @media only screen and (min-width: 1280px) #toc.toc2 { /*width: 20em;*/ width: 25em; } #doc-content a { color: #210DDC; } .top-bar h1 { border-bottom: inherit; } h2 { margin-top: 80px; } h3 { margin-top: 40px; } h4,h5 { margin-top: 30px; } .admonitionblock.tip > table td.content { color: #10B061; } .admonitionblock.note > table td.content { color: #B509AB; } .admonitionblock.important > table td.content { color: #D5810A; } .admonitionblock .title { font-size: larger; font-style: italic; } .imageblock img { margin-bottom: 10px; } </style> <style> /* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */ .header-link { position: absolute; left: -0.5em; opacity: 0; /* -webkit-transition: opacity 0.2s ease-in-out 0.1s; -moz-transition: opacity 0.2s ease-in-out 0.1s; -ms-transition: opacity 0.2s ease-in-out 0.1s; */ } h2:hover .header-link, h3:hover .header-link, h4:hover .header-link, h5:hover .header-link, h6:hover .header-link { opacity: 1; } </style> <style> .top-bar { -webkit-transition-duration: .5s; transition-duration: .5s; -webkit-transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 ); transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 ); -webkit-transition-property: -webkit-transform; transition-property: transform; } /* http://osvaldas.info/auto-hide-sticky-header MIT license */ .header--hidden { -webkit-transform: translateY( -100% ); -ms-transform: translateY( -100% ); transform: translateY( -100% ); transition-duration: .5s; transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 ); -webkit-transition-property: -webkit-transform; transition-property: transform; } </style> <style> #doc-content a.guide { color: white; } </style> <style> .tocify { margin-top: 80px; } </style> </script> </head> <body> <<div class="github-fork-ribbon-wrapper right" style="position: fixed;"> <div class="github-fork-ribbon"> <a href="https://github.com/apache/isis#fork-destination-box">Fork me on GitHub</a> </div> </div> <div class="row"> <div class="fixed contain-to-grid header"> <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem"> <ul class="title-area"> <li class="name"> <h1> <a href="/index.html">Apache Isis™</a> </h1> </li>  <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li> </ul> <section class="top-bar-section"> <ul class="right"> <li class="has-form"> <FORM class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse"> <div class="row collapse"> <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya"> <INPUT type="hidden" name="cof" value="FORID:0"> <INPUT class="form-control" name="q" type="text" placeholder="Search"> </div> </FORM> </li> </ul>  <ul class="left"> <li><a href="/documentation.html">Documentation</a></li> <li><a href="/downloads.html">Downloads</a></li> <li><a href="/help.html">Help</a></li> <li><a href="/asf.html">@ASF</a></li> </ul> </section> </nav> </div> </div> <div class="row"> <div id="doc-content-left" class="large-9 medium-9 columns"> <div id="doc-content"> <div class="sect1"> <h2 id="_rgcms">1. Classes, Methods and Schema</h2> <div class="sectionbody"> <div class="paragraph"> <p>This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically reserved and prefix <a href="#_rgcms_methods">methods</a> (such as <code>title()</code> and <code>validate…()</code>) and various utility and supporting <a href="#_rgcms_classes">classes</a>.</p> </div> <div class="paragraph"> <p>It also describes the <a href="#_rgcms_schema">XSD schema</a> defined by Apache Isis. One use case is for the JAXB serialization of view models.</p> </div> <div class="sect2"> <h3 id="_other_guides">1.1. Other Guides</h3> <div class="paragraph"> <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p> </div> <div class="paragraph"> <p>The user guides available are:</p> </div> <div class="ulist"> <ul> <li> <p><a href="ugfun.html">Fundamentals</a></p> </li> <li> <p><a href="ugvw.html">Wicket viewer</a></p> </li> <li> <p><a href="ugvro.html">Restful Objects viewer</a></p> </li> <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li> <li> <p><a href="ugsec.html">Security</a></p> </li> <li> <p><a href="ugtst.html">Testing</a></p> </li> <li> <p><a href="ugbtb.html">Beyond the Basics</a></p> </li> </ul> </div> <div class="paragraph"> <p>The reference guides are:</p> </div> <div class="ulist"> <ul> <li> <p><a href="rgant.html">Annotations</a></p> </li> <li> <p><a href="rgsvc.html">Domain Services</a></p> </li> <li> <p><a href="rgcfg.html">Configuration Properties</a></p> </li> <li> <p><a href="#">Classes, Methods and Schema</a> (this guide)</p> </li> <li> <p><a href="rgmvn.html">Apache Isis Maven plugin</a></p> </li> <li> <p><a href="rgfis.html">Framework Internal Services</a></p> </li> </ul> </div> <div class="paragraph"> <p>The remaining guides are:</p> </div> <div class="ulist"> <ul> <li> <p><a href="dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li> <li> <p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_rgcms_methods">2. Methods</h2> <div class="sectionbody"> <div class="paragraph"> <p>The Apache Isis metamodel is built up from declaratively (ie, <a href="rgant.html#_rgant">annotations</a>) and imperatively, from "supporting" methods and other reserved methods.</p> </div> <div class="paragraph"> <p>This chapter documents the supporting methods and the reserved methods. It also documents (separately) the reserved methods that act as callback hooks into the persistence lifecycle of domain entities.</p> </div> <div class="sect2"> <h3 id="_rgcms_methods_prefixes">2.1. Supporting Method Prefixes</h3> <div class="paragraph"> <p>Supporting methods are those that are associated with properties, collections and actions, providing additional imperative business rule checking and behaviour to be performed when the user interacts with those object members.</p> </div> <div class="paragraph"> <p>This association is performed by name matching. Thus, a property called "firstName", derived from a method <code>getFirstName()</code> may have supporting methods <code>hideFirstName()</code>, <code>disableFirstName()</code> and <code>validateFirstName()</code>. Supporting methods are, therefore, each characterized by their own particular prefix.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Using name matching to associate supporting methods generally works very well, but of course if an object member’s method is renamed, there’s always the risk that the developer forgets to rename the supporting method; the supporting methods become "orphaned".</p> </div> <div class="paragraph"> <p>Apache Isis checks for this automatically, and will fail-fast (fail to boot) if any orphaned methods are located. A suitable error message is logged so that the issue can be easily diagnosed.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The table below lists the method prefixes that are recognized as part of Apache Isis' default programming model.</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 1. Recognized Method Prefixes</caption> <colgroup> <col style="width: 18.1818%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 36.3637%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Prefix</th> <th class="tableblock halign-left valign-top">Object</th> <th class="tableblock halign-left valign-top">Property</th> <th class="tableblock halign-left valign-top">Collection</th> <th class="tableblock halign-left valign-top">Action</th> <th class="tableblock halign-left valign-top">Action<br> Param</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_addTo"><code>addTo…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>add object to a collection <br></p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_removeFrom"><code>removeFrom…()</code></a>`</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_autoComplete"><code>autoComplete…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Return a list of matching elements for a property or an action parameter.<br></p> </div> <div class="paragraph"> <p>Alternatively, can specify for a class using <a href="rgant.html#_rgant-DomainObject_autoCompleteRepository"><code>@DomainObject</code><br> <code>#autoCompleteRepository</code></a><br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_choices"><code>choices…()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_choices"><code>choices…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Provide list of choices for a property or action parameter.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_autoComplete"><code>autoComplete…()</code></a>.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_clear"><code>clear…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Clear a property (set it to null).<br></p> </div> <div class="paragraph"> <p>Allows business logic to be placed apart from the setter.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_modify"><code>modify…()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_default"><code>default…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Default value for a property or an action parameter.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_disable"><code>disable…()</code></a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Disables (makes read-only) a property, a collection or an action.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_get"><code>get…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Access the value of a property or collection.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_set"><code>set…()</code></a>.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_hide"><code>hide…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Hides a property, a collection or an action.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_modify"><code>modify…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Modify a property (set it to a non-null) value.<br></p> </div> <div class="paragraph"> <p>Allows business logic to be placed apart from the setter.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_clear"><code>clear…()</code></a>`.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_removeFrom"><code>removeFrom…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>remove object from a collection.<br></p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_addTo"><code>addTo…()</code></a>`</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_set"><code>set…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Sets the value of a property or a collection.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_validate"><code>validate…()</code></a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Check that a proposed value of a property or a set of action parameters or a single action parameter is valid.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_validateAddTo"><code>validateAddTo…()</code></a> and <a href="#_rgcms_methods_prefixes_validateRemoveFrom"><code>validateRemoveFrom…()</code></a> to validate modifications to collections.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_validateAddTo"><code>validate<br> AddTo…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Check that a proposed object to add to a collection is valid.<br></p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_validateRemoveFrom"><code>validateRemoveFrom…()</code></a>, and <a href="#_rgcms_methods_prefixes_validate"><code>validate…()</code></a> for properties and actions.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_prefixes_validateRemoveFrom"><code>validate<br> RemoveFrom…()</code></a></p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Y</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Check that a proposed object to remove from a collection is valid.<br></p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_validateAddTo"><code>validateAddTo…()</code></a>, and <a href="#_rgcms_methods_prefixes_validate"><code>validate…()</code></a> for properties and actions.</p> </div></div></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_addTo">2.1.1. <code>addTo…()</code></h4> <div class="paragraph"> <p>The <code>addTo…()</code> supporting method is called whenever an object is added to a collection. Its purpose is to allow additional business logic to be performed.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>. The suggested workaround is to simply define an action.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>For example:</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">LibraryMember</span> { <span class="directive">public</span> <span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> getBorrowed() { ... } <span class="directive">public</span> <span class="type">void</span> setBorrowed(<span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> borrowed) { ... } <span class="directive">public</span> <span class="type">void</span> addToBorrowed(<span class="predefined-type">Book</span> book) { getBorrowed().add(book); <i class="conum" data-value="1"></i><b>(1)</b> reminderService.addReminder(<span class="local-variable">this</span>, book, clock.today().plusDays(<span class="integer">21</span>)); <i class="conum" data-value="2"></i><b>(2)</b> } <span class="directive">public</span> <span class="type">void</span> removeFromBorrowed(<span class="predefined-type">Book</span> book) { ... } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>update the collection</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>perform some additional business logic</td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_removeFrom"><code>removeFrom…()</code></a>`</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_autoComplete">2.1.2. <code>autoComplete…()</code></h4> <div class="paragraph"> <p>The <code>autoComplete…()</code> supporting method is called for action parameters and for properties to find objects from a drop-down list box. The use case is when the number of candidate objects is expected to be large, so the user is required to enter some characters to narrow the search down.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>If the number of candidate objects is comparatively small, then use <a href="#_rgcms_methods_prefixes_choices"><code>choices…()</code></a> supporting method instead.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The signature of the supporting method depends on whether it is for a parameter or a property.</p> </div> <div class="sect4"> <h5 id="_parameters">Parameters</h5> <div class="paragraph"> <p>For an action parameter in (0-based) position <em>N</em>, and of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">List</span><T> autoCompleteNXxx(<span class="predefined-type">String</span> search) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>It is also valid to return <code>T[]</code>, a <code>Set<T></code> or a <code>Collection<T></code>.</p> </div> <div class="paragraph"> <p>For example:</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">ShoppingCartItem</span> { <span class="annotation">@Property</span>(editing=Editing.DISABLED) <span class="directive">public</span> Product getProduct() { ... } <span class="directive">public</span> <span class="type">void</span> setProduct(Product product) { ... } <span class="annotation">@Property</span>(editing=Editing.DISABLED) <span class="directive">public</span> <span class="type">int</span> getQuantity() { ... } <span class="directive">public</span> <span class="type">void</span> setQuantity(<span class="type">int</span> quantity) { ... } <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT) <span class="directive">public</span> ShoppingCartItem updateProduct( Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="type">int</span> quantity) { setProduct(product); setQuantity(quantity); } <span class="directive">public</span> <span class="predefined-type">Collection</span><Product> autoComplete0UpdateProduct( <i class="conum" data-value="1"></i><b>(1)</b> <span class="annotation">@MinLength</span>(<span class="integer">3</span>) <span class="predefined-type">String</span> search <i class="conum" data-value="2"></i><b>(2)</b> ) { ... } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td><code>product</code> is the 0th argument of the action.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the <a href="rgant.html#_rgant-MinLength"><code>@MinLength</code></a> annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects</td> </tr> </table> </div> </div> <div class="sect4"> <h5 id="_properties">Properties</h5> <div class="paragraph"> <p>For a property of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">List</span><T> autoCompleteXxx(<span class="predefined-type">String</span> search) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>(As for action parameters) it is also valid to return <code>T[]</code>, a <code>Set<T></code> or a <code>Collection<T></code>.</p> </div> <div class="paragraph"> <p>For example:</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">ShoppingCartItem</span> { <span class="directive">public</span> Product getProduct() { ... } <span class="directive">public</span> <span class="type">void</span> setProduct(Product product) { ... } <span class="directive">public</span> <span class="predefined-type">Collection</span><Product> autoCompleteProduct( <span class="annotation">@MinLength</span>(<span class="integer">3</span>) <span class="predefined-type">String</span> search <i class="conum" data-value="1"></i><b>(1)</b> ) { ... } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the <a href="rgant.html#_rgant-MinLength"><code>@MinLength</code></a> annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects</td> </tr> </table> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_choices">2.1.3. <code>choices…()</code></h4> <div class="paragraph"> <p>The <code>choices…()</code> supporting method is called for both action parameters and for properties, to find objects from a drop-down list box. Unlike <a href="#_rgcms_methods_prefixes_autoComplete"><code>autoComplete…()</code></a>, the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.</p> </div> <div class="paragraph"> <p>The signature of the supporting method depends on whether it is for an action parameter or a property.</p> </div> <div class="sect4"> <h5 id="_parameters_2">Parameters</h5> <div class="paragraph"> <p>For an action parameter in (0-based) position <em>N</em>, and of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">Collection</span><T> choicesNXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>For example:</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">ShoppingCartItem</span> { <span class="annotation">@Property</span>(editing=Editing.DISABLED) <span class="directive">public</span> Product getProduct() { ... } <span class="directive">public</span> <span class="type">void</span> setProduct(Product product) { ... } <span class="annotation">@Property</span>(editing=Editing.DISABLED) <span class="directive">public</span> <span class="type">int</span> getQuantity() { ... } <span class="directive">public</span> <span class="type">void</span> setQuantity(<span class="type">int</span> quantity) { ... } <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT) <span class="directive">public</span> ShoppingCartItem updateProduct( Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="predefined-type">Integer</span> quantity) { setProduct(product); setQuantity(quantity); } <span class="directive">public</span> <span class="predefined-type">Collection</span><<span class="predefined-type">Integer</span>> choices1UpdateProduct() { <span class="keyword">return</span> <span class="predefined-type">Arrays</span>.asList(<span class="integer">1</span>,<span class="integer">2</span>,<span class="integer">3</span>,<span class="integer">5</span>,<span class="integer">10</span>,<span class="integer">25</span>,<span class="integer">50</span>,<span class="integer">100</span>); } ... }</code></pre> </div> </div> <div class="sect5"> <h6 id="_dependent_choices">Dependent Choices</h6> <div class="paragraph"> <p>Action parameters also support the notion of dependent choices, whereby the list of choices is dependent upon the value of some other argument.</p> </div> <div class="paragraph"> <p>An example can be found in the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, whereby `ToDoItem`s are categorized and then can also be subcategorized:</p> </div> <div class="imageblock"> <div class="content"> <a class="image" href="images/reference-methods/prefixes/choices/dependent.png"><img src="images/reference-methods/prefixes/choices/dependent.png" alt="dependent" width="800px"></a> </div> </div> <div class="paragraph"> <p>This functionality is actually implemented as a <a href="ugfun.html#_ugfun_how-tos_contributed-members">contributed action</a>, so the code for this is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY) <span class="directive">public</span> <span class="type">class</span> <span class="class">UpdateCategoryContributions</span> ... { <span class="annotation">@ActionLayout</span>( describedAs = <span class="string"><span class="delimiter">"</span><span class="content">Update category and subcategory</span><span class="delimiter">"</span></span> ) <span class="annotation">@Action</span>(semantics = SemanticsOf.IDEMPOTENT) <span class="directive">public</span> Categorized updateCategory( <span class="directive">final</span> Categorized item, <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">final</span> Category category, <span class="annotation">@Parameter</span>(optionality = Optionality.OPTIONAL) <span class="directive">final</span> Subcategory subcategory) { item.setCategory(category); item.setSubcategory(subcategory); <span class="keyword">return</span> item; } <span class="directive">public</span> <span class="predefined-type">List</span><Subcategory> choices2UpdateCategory( <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">final</span> Categorized item, <i class="conum" data-value="3"></i><b>(3)</b> <span class="directive">final</span> Category category) { <i class="conum" data-value="4"></i><b>(4)</b> <span class="keyword">return</span> Subcategory.listFor(category); } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td><code>ToDoItem</code> implements <code>Categorized</code></td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>subcategory is the 2-th argument (0-based)</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the item contributed to</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the category selected</td> </tr> </table> </div> <div class="paragraph"> <p>Dependent choices are not restricted to enums, however. Going back to the shopping cart example shown above, the choices for the <code>quantity</code> parameter could be dependent upon the selected <code>Product</code>:</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">ShoppingCartItem</span> { ... <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT) <span class="directive">public</span> ShoppingCartItem updateProduct( Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="predefined-type">Integer</span> quantity) { setProduct(product); setQuantity(quantity); } <span class="directive">public</span> <span class="predefined-type">Collection</span><<span class="predefined-type">Integer</span>> choices1UpdateProduct(Product product) { <span class="keyword">return</span> productService.quantityChoicesFor(product); <i class="conum" data-value="1"></i><b>(1)</b> } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td><code>productService</code> is a (fictitous) injected service that knows what the quantity choices should be for any given product</td> </tr> </table> </div> </div> </div> <div class="sect4"> <h5 id="_properties_2">Properties</h5> <div class="paragraph"> <p>For a property of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">Collection</span><T> choicesXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>For example:</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">ShoppingCartItem</span> { <span class="directive">public</span> Product getProduct() { ... } <span class="directive">public</span> <span class="type">void</span> setProduct(Product product) { ... } <span class="directive">public</span> <span class="predefined-type">Collection</span><Product> choicesProduct() { ... }</code></pre> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_clear">2.1.4. <code>clear…()</code></h4> <div class="paragraph"> <p>The <code>clear…()</code> supporting method is called — instead of the setter — whenever an (optional) property is to be set to <code>null</code>. Its purpose is to allow additional business logic to be performed.</p> </div> <div class="paragraph"> <p>For example:</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">LibraryMember</span> { <span class="directive">public</span> Title getFavoriteTitle() { ... } <span class="directive">public</span> <span class="type">void</span> setFavoriteTitle(Title title) { ... } <span class="directive">public</span> <span class="type">void</span> modifyFavoriteTitle(Title title) { ... } <span class="directive">public</span> <span class="type">void</span> clearFavoriteTitle() { <span class="keyword">if</span>(getTitle() == <span class="predefined-constant">null</span>) { <span class="keyword">return</span>; } setFavoriteTitle(<span class="predefined-constant">null</span>); <i class="conum" data-value="1"></i><b>(1)</b> titleFavoritesService.decrement(title); <i class="conum" data-value="2"></i><b>(2)</b> } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>update the property</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>perform some additional business logic</td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_modify"><code>modify…()</code></a>`</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_default">2.1.5. <code>default…()</code></h4> <div class="paragraph"> <p>The <code>default…()</code> supporting method is called for action parameters to return the initial argument value. This may be some sensible default (eg today’s date, or 0 or 1), or — for an action that is modifying the state of an object — might default to the current value of a corresponding property.</p> </div> <div class="paragraph"> <p>The method is <em>also</em> called for properties in the case when an object is newly instantiated using <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer#newTransientInstance(…)</code></a>. This is a much less common use case. If a default is not specified then properties are initialized to a default based on their type (eg 0 or <code>false</code>).</p> </div> <div class="paragraph"> <p>The signature of the supporting method depends on whether it is for an action parameter or a property.</p> </div> <div class="sect4"> <h5 id="_parameters_3">Parameters</h5> <div class="paragraph"> <p>For an action parameter in (0-based position n), and of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> T defaultNXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>For example:</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">ShoppingCartItem</span> { <span class="annotation">@Property</span>(editing=Editing.DISABLED) <span class="directive">public</span> Product getProduct() { ... } <span class="directive">public</span> <span class="type">void</span> setProduct(Product product) { ... } <span class="annotation">@Property</span>(editing=Editing.DISABLED) <span class="directive">public</span> <span class="type">int</span> getQuantity() { ... } <span class="directive">public</span> <span class="type">void</span> setQuantity(<span class="type">int</span> quantity) { ... } <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT) <span class="directive">public</span> ShoppingCartItem updateProduct( Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="predefined-type">Integer</span> quantity) { setProduct(product); setQuantity(quantity); } <span class="directive">public</span> Product default0UpdateProduct() { <i class="conum" data-value="1"></i><b>(1)</b> <span class="keyword">return</span> getProduct(); } <span class="directive">public</span> <span class="type">int</span> default1UpdateProduct() { <i class="conum" data-value="2"></i><b>(2)</b> <span class="keyword">return</span> getQuantity(); } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>default the 0-th parameter using the current value of the <code>product</code> property</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>default the 1-th parameter using the current value of the <code>quantity</code> property</td> </tr> </table> </div> <div class="paragraph"> <p>Defaults are also supported (of course) for <a href="ugfun.html#_ugfun_how-tos_contributed-members">contributed actions</a>. For example, here is a contributed action for updating category/subcategory of the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY) <span class="directive">public</span> <span class="type">class</span> <span class="class">UpdateCategoryContributions</span> ... { <span class="annotation">@ActionLayout</span>( describedAs = <span class="string"><span class="delimiter">"</span><span class="content">Update category and subcategory</span><span class="delimiter">"</span></span> ) <span class="annotation">@Action</span>(semantics = SemanticsOf.IDEMPOTENT) <span class="directive">public</span> Categorized updateCategory( <span class="directive">final</span> Categorized item, <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">final</span> Category category, <span class="annotation">@Parameter</span>(optionality = Optionality.OPTIONAL) <span class="directive">final</span> Subcategory subcategory) { item.setCategory(category); item.setSubcategory(subcategory); <span class="keyword">return</span> item; } <span class="directive">public</span> Category default1UpdateCategory( <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">final</span> Categorized item) { <span class="keyword">return</span> item != <span class="predefined-constant">null</span>? item.getCategory(): <span class="predefined-constant">null</span>; } <span class="directive">public</span> Subcategory default2UpdateCategory( <i class="conum" data-value="3"></i><b>(3)</b> <span class="directive">final</span> Categorized item) { <span class="keyword">return</span> item != <span class="predefined-constant">null</span>? item.getSubcategory(): <span class="predefined-constant">null</span>; } }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td><code>ToDoItem</code> implements <code>Categorized</code></td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>defaults the 1-th parameter using the item’s <code>category</code> property</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>defaults the 2-th parameter using the item’s <code>subcategory</code> property</td> </tr> </table> </div> </div> <div class="sect4"> <h5 id="_properties_3">Properties</h5> <div class="paragraph"> <p>For a property of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> T defaultXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>For example:</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">ShoppingCartItem</span> { <span class="directive">public</span> <span class="type">int</span> getQuantity() { ... } <span class="directive">public</span> <span class="type">void</span> setQuantity(<span class="type">int</span> quantity) { ... } <span class="directive">public</span> <span class="type">int</span> defaultProduct() { <span class="keyword">return</span> <span class="integer">1</span>; }</code></pre> </div> </div> <div class="sect5"> <h6 id="_alternatives">Alternatives</h6> <div class="paragraph"> <p>There are, in fact, two other ways to set properties of a newly instantiated object to default values.</p> </div> <div class="paragraph"> <p>The first is to use the <a href="#_rgcms_methods_lifecycle_created"><code>created()</code></a> callback, called by the framework when <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer#newTransientInstance(…)</code></a> is called. This method is called after any dependencies have been injected into the service.</p> </div> <div class="paragraph"> <p>The second is more straightforward: simply initialize properties in the constructor. However, this cannot use any injected services as they will not have been initialized.</p> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_disable">2.1.6. <code>disable…()</code></h4> <div class="paragraph"> <p>The <code>disable…()</code> supporting method is called for properties, collections and actions. It allows the modification of the property/collection to be vetoed (ie made read-only) and to prevent the invocation of the action ("grey it out").</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>; they are always implicitly disabled.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).</p> </div> <div class="paragraph"> <p>The reason for vetoing a modification/invocation is normally returned as a string. However, Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that reasons can be internationalized.</p> </div> <div class="sect4"> <h5 id="_actions">Actions</h5> <div class="paragraph"> <p>For an action the signature of the supporting method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> disableXxx(...) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason the action invocation is vetoed (or <code>null</code> if not vetoed), and the supporting method takes the same parameter types as the action itself.</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> <span class="type">boolean</span> isBlacklisted() { ... } <span class="directive">public</span> Order placeOrder( <span class="directive">final</span> Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="type">int</span> quantity) { ... } <span class="directive">public</span> <span class="predefined-type">String</span> disablePlaceOrder( <span class="directive">final</span> Product product, <span class="directive">final</span> <span class="type">int</span> quantity ) { <span class="keyword">return</span> isBlacklisted() ? <span class="string"><span class="delimiter">"</span><span class="content">Blacklisted customers cannot place orders</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } ... }</code></pre> </div> </div> </div> <div class="sect4"> <h5 id="_properties_and_collections">Properties and Collections</h5> <div class="paragraph"> <p>For both properties and collections the signature of the supporting method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> disableXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason the modification is vetoed (or <code>null</code> if not vetoed).</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> <span class="type">boolean</span> isBlacklisted() { ... } <span class="directive">public</span> <span class="predefined-type">BigDecimal</span> getCreditLimit() { ... } <span class="directive">public</span> <span class="type">void</span> setCreditLimit(<span class="predefined-type">BigDecimal</span> creditLimit) { ... } <span class="directive">public</span> <span class="predefined-type">String</span> disableCreditLimit() { <span class="keyword">return</span> isBlacklisted() ? <span class="string"><span class="delimiter">"</span><span class="content">Cannot change credit limit for blacklisted customers</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } ... }</code></pre> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_get">2.1.7. <code>get…()</code></h4> <div class="paragraph"> <p>The <code>get…()</code> prefix is simply the normal JavaBean getter prefix that denotes properties or collections.</p> </div> <div class="paragraph"> <p>When Apache Isis builds its metamodel, it first searches for the getter methods, characterizing them as either properties or collections based on the return type. It then refines the metamodel based on the presence of annotations and supporting methods.</p> </div> <div class="paragraph"> <p>All remaining <code>public</code> methods (that do not use one of the Apache Isis prefixes) are interpreted as actions.</p> </div> <div class="paragraph"> <p>Any methods "left over" that <em>do</em> use one of the Apache Isis prefixes, are interpreted to be orphaned. Apache Isis "fails-fast" and will not boot, instead printing an error message to the log so that the issue can be easily diagnosed.</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_set"><code>set…()</code></a>.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_hide">2.1.8. <code>hide…()</code></h4> <div class="paragraph"> <p>The <code>hide…()</code> supporting method is called for properties, collections and actions. It allows the property/collection to be completely hidden from view.</p> </div> <div class="paragraph"> <p>It’s comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just <a href="#_rgcms_methods_prefixes_disable">disabled</a>, ie greyed out).</p> </div> <div class="sect4"> <h5 id="_actions_2">Actions</h5> <div class="paragraph"> <p>For an action the signature of the supporting method is either:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">boolean</span> hideXxx(...) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the supporting method takes the same parameter types as the action itself, or more simply:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">boolean</span> hideXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>with no parameters at all. Returning <code>true</code> will hide the action, returning <code>false</code> leaves it visible.</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> <span class="type">boolean</span> isBlacklisted() { ... } <span class="directive">public</span> Order placeOrder( <span class="directive">final</span> Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="type">int</span> quantity) { ... } <span class="directive">public</span> <span class="type">boolean</span> hidePlaceOrder() { <span class="keyword">return</span> isBlacklisted(); } ... }</code></pre> </div> </div> </div> <div class="sect4"> <h5 id="_properties_and_collections_2">Properties and Collections</h5> <div class="paragraph"> <p>For both properties and collections the signature of the supporting method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">boolean</span> hideXxx() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where returning <code>true</code> will hide the property/collection, returning <code>false</code> leaves it visible.</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> <span class="type">boolean</span> isBlacklisted() { ... } <span class="directive">public</span> <span class="predefined-type">BigDecimal</span> getCreditLimit() { ... } <span class="directive">public</span> <span class="type">void</span> setCreditLimit(<span class="predefined-type">BigDecimal</span> creditLimit) { ... } <span class="directive">public</span> <span class="type">boolean</span> hideCreditLimit() { <span class="keyword">return</span> isBlacklisted(); } ... }</code></pre> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_modify">2.1.9. <code>modify…()</code></h4> <div class="paragraph"> <p>The <code>modify…()</code> supporting method is called — instead of the setter — whenever a property has been set to be set to a new value. Its purpose is to allow additional business logic to be performed.</p> </div> <div class="paragraph"> <p>For example:</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">LibraryMember</span> { <span class="directive">public</span> Title getFavoriteTitle() { ... } <span class="directive">public</span> <span class="type">void</span> setFavoriteTitle(Title title) { ... } <span class="directive">public</span> <span class="type">void</span> modifyFavoriteTitle(Title title) { <span class="keyword">if</span>(getTitle() != <span class="predefined-constant">null</span>) { titleFavoritesService.decrement(getTitle()); <i class="conum" data-value="1"></i><b>(1)</b> } setFavoriteTitle(title); <i class="conum" data-value="2"></i><b>(2)</b> titleFavoritesService.decrement(title); <i class="conum" data-value="3"></i><b>(3)</b> } <span class="directive">public</span> <span class="type">void</span> clearFavoriteTitle() { ... } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>perform some additional business logic</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>update the property</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>perform some additional business logic</td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_clear"><code>clear…()</code></a>`</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_removeFrom">2.1.10. <code>removeFrom…()</code></h4> <div class="paragraph"> <p>The <code>removeFrom…()</code> supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>. The suggested workaround is to simply define an action.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>For example:</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">LibraryMember</span> { <span class="directive">public</span> <span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> getBorrowed() { ... } <span class="directive">public</span> <span class="type">void</span> setBorrowed(<span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> borrowed) { ... } <span class="directive">public</span> <span class="type">void</span> addToBorrowed(<span class="predefined-type">Book</span> book) { ... } <span class="directive">public</span> <span class="type">void</span> removeFromBorrowed(<span class="predefined-type">Book</span> book) { getBorrowed().remove(book); <i class="conum" data-value="1"></i><b>(1)</b> reminderService.removeReminder(<span class="local-variable">this</span>, book); <i class="conum" data-value="2"></i><b>(2)</b> } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>update the collection</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>perform some additional business logic</td> </tr> </table> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_addTo"><code>addTo…()</code></a>`</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_set">2.1.11. <code>set…()</code></h4> <div class="paragraph"> <p>The <code>set…()</code> prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_get"><code>get…()</code></a>.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_validate">2.1.12. <code>validate…()</code></h4> <div class="paragraph"> <p>The <code>validate…()</code> supporting method is called for properties, actions and action parameters. It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.</p> </div> <div class="paragraph"> <p>The reason for vetoing a modification/invocation is normally returned as a string. However, Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that reasons can be internationalized if required.</p> </div> <div class="sect4"> <h5 id="_action_parameter">Action Parameter</h5> <div class="paragraph"> <p>For an action parameter in (0-based) position <em>N</em>, and of type <code>T</code>, the signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> validateNXxx(T proposed) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason why the argument is rejected (or <code>null</code> if not vetoed).</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> Order placeOrder( <span class="directive">final</span> Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="type">int</span> quantity) { ... } <span class="directive">public</span> <span class="predefined-type">String</span> validate0PlaceOrder( <span class="directive">final</span> Product product) { <span class="keyword">return</span> product.isDiscontinued() ? <span class="string"><span class="delimiter">"</span><span class="content">Product has been discontinued</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } ... }</code></pre> </div> </div> </div> <div class="sect4"> <h5 id="_action_parameter_set">Action Parameter Set</h5> <div class="paragraph"> <p>In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments. The signature is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> validateXxx(...) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason why the argument is rejected (or <code>null</code> if not vetoed), and the supporting method takes the same parameter types as the action itself.</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> Order placeOrder( <span class="directive">final</span> Product product, <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="type">int</span> quantity) { ... } <span class="directive">public</span> <span class="predefined-type">String</span> validatePlaceOrder( <span class="directive">final</span> Product product, <span class="directive">final</span> <span class="type">int</span> quantity) { <span class="keyword">return</span> quantity > product.getOrderLimit() ? <span class="string"><span class="delimiter">"</span><span class="content">May not order more than </span><span class="delimiter">"</span></span> + product.getOrderLimit() + <span class="string"><span class="delimiter">"</span><span class="content"> items for this product</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } ... }</code></pre> </div> </div> </div> <div class="sect4"> <h5 id="_properties_4">Properties</h5> <div class="paragraph"> <p>For properties of type <code>T</code> the signature of the supporting method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> validateXxx(T proposed) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason the modification is vetoed (or <code>null</code> if not vetoed).</p> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { <span class="directive">public</span> <span class="predefined-type">BigDecimal</span> getCreditLimit() { ... } <span class="directive">public</span> <span class="type">void</span> setCreditLimit(<span class="predefined-type">BigDecimal</span> creditLimit) { ... } <span class="directive">public</span> validateCreditLimit(<span class="predefined-type">BigDecimal</span> creditLimit) { <span class="keyword">return</span> creditLimit.compareTo(<span class="predefined-type">BigDecimal</span>.ZERO) < <span class="integer">0</span> ? <span class="string"><span class="delimiter">"</span><span class="content">Credit limit cannot be negative</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } ... }</code></pre> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_validateAddTo">2.1.13. <code>validateAddTo…()</code></h4> <div class="paragraph"> <p>The <code>validateAddTo…()</code> supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>. The suggested workaround is to simply define an action.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The signature of the supporting method for a collection with element type <code>E</code> is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> validateAddToXxx(E element) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason the collection modification invocation is vetoed (or <code>null</code> if not vetoed). Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that reasons can be internationalized if required.</p> </div> <div class="paragraph"> <p>For example:</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">LibraryMember</span> { <span class="directive">public</span> <span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> getBorrowed() { ... } <span class="directive">public</span> <span class="type">void</span> setBorrowed(<span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> borrowed) { ... } <span class="directive">public</span> <span class="predefined-type">String</span> validateAddToBorrowed(<span class="predefined-type">Book</span> book) { <span class="keyword">return</span> book.isReference()? <span class="string"><span class="delimiter">"</span><span class="content">Reference books cannot be borrowed</span><span class="delimiter">"</span></span>: <span class="predefined-constant">null</span>; } <span class="directive">public</span> <span class="type">void</span> validateRemoveFromBorrowed(<span class="predefined-type">Book</span> book) { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_addTo"><code>addTo…()</code></a> and <a href="#_rgcms_methods_prefixes_validateRemoveFrom"><code>validateRemoveFrom…()</code></a>`</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_prefixes_validateRemoveFrom">2.1.14. <code>validateRemoveFrom…()</code></h4> <div class="paragraph"> <p>The <code>validateRemoveFrom…()</code> supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Directly mutable collections are not currently supported by the <a href="ugvw.html">Wicket viewer</a>. The suggested workaround is to simply define an action.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The signature of the supporting method for a collection with element type <code>E</code> is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> validateRemoveFromXxx(E element) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason the collection modification invocation is vetoed (or <code>null</code> if not vetoed). Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that reasons can be internationalized if required.</p> </div> <div class="paragraph"> <p>For example:</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">LibraryMember</span> { <span class="directive">public</span> <span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> getBorrowed() { ... } <span class="directive">public</span> <span class="type">void</span> setBorrowed(<span class="predefined-type">SortedSet</span><<span class="predefined-type">Book</span>> borrowed) { ... } <span class="directive">public</span> <span class="predefined-type">String</span> validateAddToBorrowed(<span class="predefined-type">Book</span> book) { ... } <span class="directive">public</span> <span class="type">void</span> validateRemoveFromBorrowed(<span class="predefined-type">Book</span> book) { <span class="keyword">return</span> !book.hasBeenReadBy(<span class="local-variable">this</span>)? <span class="string"><span class="delimiter">"</span><span class="content">You didn't read this book yet</span><span class="delimiter">"</span></span>: <span class="predefined-constant">null</span>; } ... }</code></pre> </div> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_prefixes_removeFrom"><code>removeFrom…()</code></a> and <a href="#_rgcms_methods_prefixes_validateAddTo"><code>validateAddTo…()</code></a>`</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_methods_reserved">2.2. Reserved Methods</h3> <div class="paragraph"> <p>The table below lists the reserved methods that are recognized as part of Apache Isis' default programming model.</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 2. Reserved Methods</caption> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Method</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Provides a CSS class for this object instance. In conjunction with <a href="rgcfg.html#_rgcfg_application-specific_application-css"><code>application.css</code></a>, can therefore provide custom styling of an object instance wherever it is rendered.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> and <a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a>.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_disable"><code>disable(…)</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Disable all or some of an object’s properties</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_getId"><code>getId()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Provides an optional unique identifier of a service.<br></p> </div> <div class="paragraph"> <p>If not provided, the service’s fully-qualified class name is used.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_hide"><code>hide(…)</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Hide all or some of an object’s properties</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> and <a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_title"><code>title()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Provides a title for the object.<br></p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a> and <a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_reserved_validate"><code>validate()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Validate the object’s state prior to persisting.</p> </div></div></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_methods_reserved_cssClass">2.2.1. <code>cssClass()</code></h4> <div class="paragraph"> <p>The <code>cssClass()</code> returns a CSS class for a particular object instance.</p> </div> <div class="paragraph"> <p>The <a href="ugvw.html">Wicket viewer</a> wraps the object’s representation in a containing <code><div></code> with the class added. This is done both for rendering the object either in a table or when rendering the object on its own page.</p> </div> <div class="paragraph"> <p>In conjunction with <a href="rgcfg.html#_rgcfg_application-specific_application-css"><code>application.css</code></a>, can therefore provide custom styling of an object instance wherever it is rendered.<br></p> </div> <div class="paragraph"> <p>For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> uses this technique to add a strikethrough for completed todo items. This is shown on the home page:</p> </div> <div class="imageblock"> <div class="content"> <a class="image" href="images/reference-methods/reserved/cssClass/strikethrough.png"><img src="images/reference-methods/reserved/cssClass/strikethrough.png" alt="strikethrough" width="800px"></a> </div> </div> <div class="paragraph"> <p>The code to accomplish this is straightforward:</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">ToDoItem</span> ... { <span class="directive">public</span> <span class="predefined-type">String</span> cssClass() { <span class="keyword">return</span> !isComplete() ? <span class="string"><span class="delimiter">"</span><span class="content">todo</span><span class="delimiter">"</span></span> : <span class="string"><span class="delimiter">"</span><span class="content">done</span><span class="delimiter">"</span></span>; } ... }</code></pre> </div> </div> <div class="paragraph"> <p>In the <a href="rgcfg.html#_rgcfg_application-specific_application-css">application.css</a>, the following styles were then added:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="css"><span class="tag">tr</span><span class="class">.todo</span> { } <span class="tag">tr</span><span class="class">.done</span> { <span class="key">text-decoration</span>: <span class="value">line-through</span>; <span class="key">color</span>: <span class="color">#d3d3d3</span>; }</code></pre> </div> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> and <a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a>.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_disable">2.2.2. <code>disable()</code></h4> <div class="paragraph"> <p>One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.</p> </div> <div class="paragraph"> <p>It would be painful to have to write a separate <a href="#_rgcms_methods_prefixes_disable"><code>disable…()</code></a> method for each and every member, so instead Isis allows a single <code>disable…(…)</code> method to be implemented that is applied to all members.</p> </div> <div class="paragraph"> <p>The signature of the method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> disable(Identifier.Type identifierType) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where <code>Identifier.Type</code> is part of the Isis applib (nested static class of <code>o.a.i.applib.Identifier</code>) to distinguish between an interaction with an action, a property or an action.</p> </div> <div class="paragraph"> <p>Note that Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that the returned reason can also be internationalized.</p> </div> <div class="paragraph"> <p>For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> disable(Identifier.Type identifierType) { <span class="keyword">return</span> !calendarService.isOfficeHours(clock.today() ? <span class="string"><span class="delimiter">"</span><span class="content">Cannot modify objects outside of office hours</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; }</code></pre> </div> </div> <div class="paragraph"> <p>See also the similar methods to <a href="#_rgcms_methods_reserved_hide"><code>hide()</code></a> object members en-masse.</p> </div> <div class="sect4"> <h5 id="_alternatives_2">Alternatives</h5> <div class="paragraph"> <p>An alternative design — and one that could be easily argued is actually more flexible — is to leverage domain events with vetoing subscribers.</p> </div> <div class="paragraph"> <p>With this approach we define, for a given domain class, a base <code>PropertyDomainEvent</code>, <code>CollectionDomainEvent</code> and <code>ActionDomainEvent</code>. A good pattern is to make these nested static classes. For example:</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">ToDoItem</span> ... { <span class="directive">public</span> <span class="directive">static</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PropertyDomainEvent</span><T> <span class="directive">extends</span> ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>where in turn:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">ToDoAppDomainModule</span> { <span class="directive">private</span> ToDoAppDomainModule(){} <span class="directive">public</span> <span class="directive">abstract</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">PropertyDomainEvent</span><S,T> <span class="directive">extends</span> org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>Then, each property/collection/action emits either these base domain events or their own subclass:</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">ToDoItem</span> ... { <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">DescriptionDomainEvent</span> <span class="directive">extends</span> PropertyDomainEvent<<span class="predefined-type">String</span>> { ... } <span class="annotation">@Property</span>( domainEvent = DescriptionDomainEvent.class ) <span class="directive">public</span> <span class="predefined-type">String</span> getDescription() { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>A vetoing subscriber can then subscribe to the domain events and veto access, eg:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span> <span class="directive">public</span> <span class="type">class</span> <span class="class">VetoOutOfOfficeHours</span> { <span class="annotation">@Subscribe</span> <span class="directive">public</span> <span class="type">void</span> on(ToDoItem.PropertyDomainEvent ev) { <span class="keyword">if</span>(!calendarService.isOfficeHours(clock.today()) { ev.veto(<span class="string"><span class="delimiter">"</span><span class="content">Cannot modify objects outside of office hours</span><span class="delimiter">"</span></span>); } } ... }</code></pre> </div> </div> <div class="paragraph"> <p>Obviously there’s an awful lot more boilerplate here, but there’s also a lot more flexibility.</p> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_getId">2.2.3. <code>getId()</code></h4> <div class="paragraph"> <p>The <code>getId()</code> method applies only to domain services, and allows a unique identifer to be provided for that service.</p> </div> <div class="paragraph"> <p>This identifier corresponds in many ways to the <a href="rgant.html#_rgant-DomainObject_objectType"><code>objectType()</code></a> attribute for domain objects; it is used as an internal identifier but also appears in URLs within the <a href="ugvro.html">RestfulObjects viewer</a>'s REST API.</p> </div> <div class="paragraph"> <p>If the identifier is omitted, the services fully qualified class name is used.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Unlike domain objects, where the use of an object type is strongly encouraged (eg using <a href="rgant.html#_rgant-PersistenceCapable"><code>@PersistenceCapable</code></a>), it matters much less if an id is specified for domain services. The principle benefit is shorter URLs in the REST API.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_hide">2.2.4. <code>hide()</code></h4> <div class="paragraph"> <p>One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object’s members should be hidden. For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.</p> </div> <div class="paragraph"> <p>While we could write a separate <a href="#_rgcms_methods_prefixes_hide"><code>hide…()</code></a> method for each and every action, this could become painful. So instead Isis allows a single <code>hide…(…)</code> method to be implemented that is applied to all members.</p> </div> <div class="paragraph"> <p>The signature of the method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">boolean</span> hide(Identifier.Type identifierType) { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where <code>Identifier.Type</code> is part of the Isis applib (nested static class of <code>o.a.i.applib.Identifier</code>) to distinguish between an interaction with an action, a property or an action.</p> </div> <div class="paragraph"> <p>For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">boolean</span> hide(Identifier.Type identifierType) { <span class="keyword">return</span> identifierType == Identifier.Type.ACTION && isFrozen(); }</code></pre> </div> </div> <div class="paragraph"> <p>See also the similar method to <a href="#_rgcms_methods_reserved_disable"><code>disable()</code></a> object members en-masse.</p> </div> <div class="sect4"> <h5 id="_alternatives_3">Alternatives</h5> <div class="paragraph"> <p>An alternative design — and one that could be easily argued is actually more flexible — is to leverage domain events with vetoing subscribers.</p> </div> <div class="paragraph"> <p>There is further discussion on this approach in <a href="#_rgcms_methods_reserved_disable">here</a>.</p> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_iconName">2.2.5. <code>iconName()</code></h4> <div class="paragraph"> <p>Every object is represented by an icon; this is based on the domain object’s simple name. The <a href="ugvw.html">Wicket viewer</a> searches for the image in the same package as the <code>.class</code> file for the domain object or in the <code>images</code> package. It will find any matching name and one of the followign suffexes <code>png</code>, <code>gif</code>, <code>jpeg</code>, <code>jpg</code>, <code>svg</code>. If none is found, then <code>Default.png</code> will be used as fallback.</p> </div> <div class="paragraph"> <p>The <code>iconName()</code> allows the icon that to be used to change for individual object instances. These are usually quite subtle, for example to reflect the particular status of an object. The value returned by the <code>iconName()</code> method is added as a suffix to the base icon name.</p> </div> <div class="paragraph"> <p>For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> uses this technique to add an overlay for todo items that have been completed:</p> </div> <div class="imageblock"> <div class="content"> <a class="image" href="images/reference-methods/reserved/iconName/differing.png"><img src="images/reference-methods/reserved/iconName/differing.png" alt="differing" width="200px"></a> </div> </div> <div class="paragraph"> <p>The screenshot below shows the location of these png icon files:</p> </div> <div class="imageblock"> <div class="content"> <a class="image" href="images/reference-methods/reserved/iconName/png-files.png"><img src="images/reference-methods/reserved/iconName/png-files.png" alt="png files" width="200px"></a> </div> </div> <div class="paragraph"> <p>The code to accomplish this is straightforward:</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">ToDoItem</span> ... { <span class="directive">public</span> <span class="predefined-type">String</span> iconName() { <span class="keyword">return</span> !isComplete() ? <span class="string"><span class="delimiter">"</span><span class="content">todo</span><span class="delimiter">"</span></span> : <span class="string"><span class="delimiter">"</span><span class="content">done</span><span class="delimiter">"</span></span>; } ... }</code></pre> </div> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> and <a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a></p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_title">2.2.6. <code>title()</code></h4> <div class="paragraph"> <p>Every object is represented by a title. This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections. It therefore must contain enough information for the end-user to distinguish the object from any others.</p> </div> <div class="paragraph"> <p>This is most commonly done by including some unique key within the title, for example a customer’s SSN, or an order number, and so forth. However note that Apache Isis itself does <em>not</em> require the title to be unique; it is merely recommended in most cases.</p> </div> <div class="paragraph"> <p>An object’s title can be constructed in various ways, but the most flexible is to use the <code>title()</code> method. The signature of this method is usually:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> title() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>Note that Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that titles can also be internationalized.</p> </div> <div class="paragraph"> <p>For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> uses this technique to add an overlay for todo items that have been completed:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> title() { <span class="directive">final</span> TitleBuffer buf = <span class="keyword">new</span> TitleBuffer(); <i class="conum" data-value="1"></i><b>(1)</b> buf.append(getDescription()); <span class="keyword">if</span> (isComplete()) { <i class="conum" data-value="2"></i><b>(2)</b> buf.append(<span class="string"><span class="delimiter">"</span><span class="content">- Completed!</span><span class="delimiter">"</span></span>); } <span class="keyword">else</span> { <span class="keyword">try</span> { <span class="directive">final</span> LocalDate dueBy = wrapperFactory.wrap(<span class="local-variable">this</span>).getDueBy(); <i class="conum" data-value="3"></i><b>(3)</b> <span class="keyword">if</span> (dueBy != <span class="predefined-constant">null</span>) { buf.append(<span class="string"><span class="delimiter">"</span><span class="content"> due by</span><span class="delimiter">"</span></span>, dueBy); } } <span class="keyword">catch</span>(<span class="directive">final</span> HiddenException ignored) { <i class="conum" data-value="4"></i><b>(4)</b> } } <span class="keyword">return</span> buf.toString(); }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>simple <a href="#_rgcms_classes_utility_TitleBuffer">tility class</a> to help construct the title string</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>imperative conditional logic</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>using the <a href="rgsvc.html#_rgsvc_api_WrapperFactory"><code>WrapperFactory</code></a> to determine if the <code>dueBy</code> field is visible for this user …</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>… but ignore if not</td> </tr> </table> </div> <div class="paragraph"> <p>As the example above shows, the implementation can be as complex as you like.</p> </div> <div class="paragraph"> <p>In many cases, though, you may be able to use the <a href="rgant.html#_rgant-Title"><code>@Title</code></a> annotation.</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a> and <a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a></p> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_validate">2.2.7. <code>validate()</code></h4> <div class="paragraph"> <p>The <code>validate()</code> method is used to specify that invariants pertaining to an object’s state are enforced.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>(As of 1.8.0) there are known limitations with this functionality. Invariants are enforced when an object is initially created and when it is edited, however invariants are currently <em>not</em> enforced if an action is invoked.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The signature of the method is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">String</span> validate() { ... }</code></pre> </div> </div> <div class="paragraph"> <p>where the returned string is the reason that the invocation is vetoed.</p> </div> <div class="paragraph"> <p>Note that Apache Isis' <a href="ugbtb.html#_ugbtb_i18n">i18n support</a> extends this so that the returned reason can also be internationalized.</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_methods_lifecycle">2.3. Lifecycle Methods</h3> <div class="paragraph"> <p>The lifecycle callback methods notify a domain entity about its interaction within the persistence lifecycle. For example, the entity is notified immediately prior to being persisted, or when it is about to be updated.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>Note that these callbacks are fired by Apache Isis rather than JDO. In the future we may deprecate them because there are better mechanisms available using listeners/subscribers:</p> </div> <div class="ulist"> <ul> <li> <p>in Isis 1.9.0 and earlier, you may therefore want to consider using the JDO API directly to set up a lifecycle listener; see <a href="#_rgcms_methods_lifecycle_jdo-api">here</a> for further discussion.</p> </li> <li> <p>alternatively, you can use a subscriber for the <a href="#_rgcms_classes_lifecycleevent">lifecycle event</a>s fired in Isis.</p> </li> </ul> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The lifecycle callback methods supported by Isis are:</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 3. Lifecycle methods (partial support)</caption> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Method</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_created"><code>created()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when an object has just been created using <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>newTransientInstance()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_loaded"><code>loaded()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when a (persistent) object has just been loaded from the object store.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_persisted"><code>persisted()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when object has just been persisted from the object store.</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_persisting"><code>persisting()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when a (not-yet-persistent) object is just about to be persisted from the object store</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_removed"><code>removed()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when a (persistent) object has just been deleted from the object store</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_removing"><code>removing()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when a (persistent) object is just about to be deleted from the object store</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_updated"><code>updated()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when a (persistent) object has just been updated in the object store</p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_methods_lifecycle_updating"><code>updating()</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>called when a (persistent) object is just about to be updated in the object store</p> </div></div></td> </tr> </tbody> </table> <div class="paragraph"> <p>Some lifecycle methods have been deprecated:</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 4. Deprecated lifecycle methods</caption> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Method</th> <th class="tableblock halign-left valign-top">Notes</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deleted()</code></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Replaced by <a href="#_rgcms_methods_lifecycle_removed"><code>removed()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>deleting()</code></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Replaced by <a href="#_rgcms_methods_lifecycle_removing"><code>removing()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>loading()</code></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>callback for when the (persistent) object is just about to be loaded from the object store.<br></p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>This method is never called.</p> </div> </td> </tr> </table> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>saved()</code></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Replaced by <a href="#_rgcms_methods_lifecycle_persisted"><code>persisted()</code></a></p> </div></div></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>saving()</code></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p>Replaced by <a href="#_rgcms_methods_lifecycle_persisting"><code>persisting()</code></a></p> </div></div></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_methods_reserved_created">2.3.1. <code>created()</code></h4> <div class="paragraph"> <p>The <code>created()</code> lifecycle callback method is called when an object has just been created using <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>newTransientInstance()</code></a></p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectCreatedEvent"><code>ObjectCreatedEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_loaded">2.3.2. <code>loaded()</code></h4> <div class="paragraph"> <p>The <code>loaded()</code> lifecycle callback method is called when a (persistent) object has just been loaded from the object store.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectLoadedEvent"><code>ObjectLoadedEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_persisted">2.3.3. <code>persisted()</code></h4> <div class="paragraph"> <p>The <code>persisted()</code> lifecycle callback method is called when object has just been persisted from the object store.</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_lifecycle_persisting"><code>persisting()</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectPersistedEvent"><code>ObjectPersistedEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_persisting">2.3.4. <code>persisting()</code></h4> <div class="paragraph"> <p>The <code>persisting()</code> lifecycle callback method is called when a (not-yet-persistent) object is just about to be persisted from the object store</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_lifecycle_persisted"><code>persisted()</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectPersistingEvent"><code>ObjectPersistingEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_removed">2.3.5. <code>removed()</code></h4> <div class="paragraph"> <p>The <code>removed()</code> lifecycle callback method is called when a (persistent) object has just been deleted from the object store</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_lifecycle_removing"><code>removing()</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectRemovedEvent"><code>ObjectRemovedEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_removing">2.3.6. <code>removing()</code></h4> <div class="paragraph"> <p>The <code>removing()</code> lifecycle callback method is called when a (persistent) object is just about to be deleted from the object store</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_lifecycle_removed"><code>removed()</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectRemovingEvent"><code>ObjectRemovingEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_updated">2.3.7. <code>updated()</code></h4> <div class="paragraph"> <p>The <code>updated()</code> lifecycle callback method is called when a (persistent) object has just been updated in the object store</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_lifecycle_updating"><code>updating()</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent"><code>ObjectUpdatedEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_reserved_updating">2.3.8. <code>updating()</code></h4> <div class="paragraph"> <p>The <code>updating()</code> lifecycle callback method is called when a (persistent) object is just about to be updated in the object store</p> </div> <div class="paragraph"> <p>See also <a href="#_rgcms_methods_lifecycle_updated"><code>updated()</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Alternatively, consider using a <a href="rgsvc.html#_rgsvc_api_EventBusService">event bus</a> <a href="#_rgcms_classes_super_AbstractSubscriber">subscriber</a> on the <a href="#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent"><code>ObjectUpdatingEvent</code></a>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_methods_lifecycle_jdo-api">2.3.9. Using the JDO API</h4> <div class="paragraph"> <p>As an alternative to relying on Apache Isis to call lifecycle callback methods, you could instead use the JDO <a href="http://www.datanucleus.org/products/datanucleus/jdo/lifecycle_callbacks.html">lifecycle listener</a> API directly.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>We may decide to deprecate the Apache Isis callbacks in the future because they merely duplicate this functionality already available in JDO.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>You can gain access to the relevant JDO API using the <a href="rgsvc.html#_rgsvc_api_IsisJdoSupport"><code>IsisJdoSupport</code></a> domain service.</p> </div> <div class="paragraph"> <p>For example:</p> </div> <div class="listingblock"> <div class="content"> <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="2"></i><b>(2)</b> <span class="annotation">@Programmatic</span> <span class="annotation">@PostConstruct</span> <span class="directive">public</span> <span class="type">void</span> init() { getPmFactory().addInstanceLifecycleListener(<span class="local-variable">this</span>); } <span class="annotation">@Programmatic</span> <span class="annotation">@PreDestroy</span> <span class="directive">public</span> <span class="type">void</span> tidyUp() { getPmFactory().removeInstanceLifecycleListener(<span class="local-variable">this</span>); } <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) { ... } <span class="annotation">@Programmatic</span> <span class="directive">public</span> <span class="type">void</span> postStore (InstanceLifecycleEvent event) { ... } <span class="annotation">@Inject</span> IsisJdoSupport jdoSupport; }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></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>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="rgsvc.html#_rgsvc_api_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> </div> <div class="sect1"> <h2 id="_rgcms_classes">3. Classes and Interfaces</h2> <div class="sectionbody"> <div class="paragraph"> <p>This chapter describes the usage of various classes and interfaces that are not otherwise associated with <a href="#rgsvc.adoc">domain services</a>, <a href="ugfun.html#_ugfun_object-layout">object layout</a> or <a href="rgcfg.html#_rgcfg">configuration</a>.</p> </div> <div class="sect2"> <h3 id="_rgcms_classes_AppManifest-bootstrapping">3.1. <code>AppManifest</code> (bootstrapping)</h3> <div class="paragraph"> <p>This section describes how to implement the <code>AppManifest</code> interface to bootstrap both an Apache Isis web application, and also its integration tests.</p> </div> <div class="sect3"> <h4 id="_api">3.1.1. API</h4> <div class="paragraph"> <p>The <code>AppManifest</code> interface allows the constituent parts of an application to be defined programmatically, most specifically the packages that contain domain services and/or persistent entities. Its API is defined 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">interface</span> <span class="class">AppManifest</span> { <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><?>> getModules(); <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><?>> getAdditionalServices(); <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">public</span> <span class="predefined-type">String</span> getAuthenticationMechanism(); <i class="conum" data-value="3"></i><b>(3)</b> <span class="directive">public</span> <span class="predefined-type">String</span> getAuthorizationMechanism(); <i class="conum" data-value="4"></i><b>(4)</b> <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><? <span class="directive">extends</span> FixtureScript>> getFixtures(); <i class="conum" data-value="5"></i><b>(5)</b> <span class="directive">public</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>,<span class="predefined-type">String</span>> getConfigurationProperties(); <i class="conum" data-value="6"></i><b>(6)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>Must return a non-null list of classes, each of which representing the root of one of the modules containing services and possibly entities, which together makes up the running application.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>If non-<code>null</code>, overrides the value of <code>isis.services</code> configuration property to specify a list of additional classes to be instantiated as domain services (over and above the domain services defined via <code>getModules()</code> method.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>If non-<code>null</code>, overrides the value of <code>isis.authentication</code> configuration property to specify the authentication mechanism.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>If non-<code>null</code>, overrides the value of <code>isis.authorization</code> configuration property to specify the authorization mechanism.</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>If non-<code>null</code>, overrides the value of <code>isis.fixtures</code> configuration property to specify a fixture script to be installed.</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>Overrides for any other configuration properties.</td> </tr> </table> </div> <div class="paragraph"> <p>The following sections describe each of these methods in a little more detail.</p> </div> <div class="sect4"> <h5 id="__code_getmodules_code"><code>getModules()</code></h5> <div class="paragraph"> <p>The most significant method (the only one which must return a non-<code>null</code> value) is the <code>getModules()</code> method. Each module is identified by a class; the framework simply uses that class' package as the root to search for domain services (annotated with <a href="rgant.html#_rgant-DomainService"><code>@DomainService</code></a>) and entities (annotated with <a href="rgant.html#_rgant-PersistenceCapable"><code>@PersistenceCapable</code></a>). Generally there is one such module class per Maven module.</p> </div> <div class="paragraph"> <p>A module class for a domain module might for example be defined as:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">com.mycompany.myapp.dom</span>; <span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">MyAppDomainModule</span> { <span class="directive">private</span> MyAppDomainModule() {} }</code></pre> </div> </div> <div class="paragraph"> <p>This tells the framework that the package and subpackages under <code>com.mycompany.myapp.dom</code> should be searched for domain services (annotated with <code>@DomainService</code>), mixins (<code>@Mixin</code>) and entities (<code>@PersistenceCapabable</code>).</p> </div> <div class="paragraph"> <p>As is perhaps apparent, the <code>getModules()</code> method replaces and overrides both the <code>isis.services.ServicesInstallerFromAnnotation.packagePrefix</code> key (usually found in the <code>isis.properties</code> file) and also the`isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (usually found in the <code>persistor_datanucleus.properties</code> file). The value of the <code>isis.services-installer</code> configuration property is also ignored.</p> </div> <div class="paragraph"> <p>For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> defines the following:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><?>> getModules() { <span class="keyword">return</span> <span class="predefined-type">Arrays</span>.asList( ToDoAppDomainModule.class, ToDoAppFixtureModule.class, ToDoAppAppModule.class, org.isisaddons.module.audit.AuditModule.class, org.isisaddons.module.command.CommandModule.class, org.isisaddons.module.devutils.DevUtilsModule.class, org.isisaddons.module.docx.DocxModule.class, org.isisaddons.module.publishing.PublishingModule.class, org.isisaddons.module.sessionlogger.SessionLoggerModule.class, org.isisaddons.module.settings.SettingsModule.class, org.isisaddons.wicket.gmap3.cpt.service.Gmap3ServiceModule.class ); }</code></pre> </div> </div> <div class="paragraph"> <p>As can be seen, the various (non-ASF) <a href="http://isisaddons.org">Isis Addons</a> modules also each provide a module class that can be easily referenced.</p> </div> </div> <div class="sect4"> <h5 id="__code_getadditionalservices_code"><code>getAdditionalServices()</code></h5> <div class="paragraph"> <p>We normally we recommend that services are defined exclusively through <code>getModules()</code>, and that this method should therefore return an empty list. However, there are certain use cases where the a service must be explicitly specified either because the service required does not (for whatever reason) have a <a href="rgant.html#_rgant-DomainService"><code>@DomainService</code></a> annotation.</p> </div> <div class="paragraph"> <p>For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module (v1.9.0) allows the policy to evaluate conflicting permissions to be specified by explicitly registering either the <code>PermissionsEvaluationServiceAllowBeatsVeto</code> domain service or the <code>PermissionsEvaluationServiceVetoBeatsAllow</code> domain service:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><?>> getAdditionalServices() { <span class="keyword">return</span> <span class="predefined-type">Arrays</span>.asList( org.isisaddons.module.security.dom.permission.PermissionsEvaluationServiceVetoBeatsAllow.class ); }</code></pre> </div> </div> <div class="paragraph"> <p>If this method returns a non-<code>null</code> value, then it overrides the value of <code>isis.services</code> configuration property.</p> </div> </div> <div class="sect4"> <h5 id="__code_getauthenticationmechanism_code"><code>getAuthenticationMechanism()</code></h5> <div class="paragraph"> <p>If non-<code>null</code>, this method specifies the authentication mechanism to use. The valid values are currently <code>"shiro"</code> or <code>"bypass"</code>. If null is returned then the value of the <code>isis.authentication</code> configuration property (in <code>isis.properties</code> file) is used instead.</p> </div> <div class="paragraph"> <p>See the <a href="ugsec.html">security guide</a> for further details on configuring shiro or bypass security.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>This property is ignored for integration tests (which always uses the <code>"bypass"</code> mechanism).</p> </div> </td> </tr> </table> </div> </div> <div class="sect4"> <h5 id="__code_getauthorizationmechanism_code"><code>getAuthorizationMechanism()</code></h5> <div class="paragraph"> <p>If non-<code>null</code>, this method specifies the authorization mechanism to use. The valid values are currently <code>"shiro"</code> or <code>"bypass"</code>. If null is returned then the value of the <code>isis.authorization</code> configuration property (in <code>isis.properties</code> file) is used instead.</p> </div> <div class="paragraph"> <p>See the <a href="ugsec.html">security guide</a> for further details on configuring shiro or bypass security.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>This property is ignored for integration tests (which always uses the <code>"bypass"</code> mechanism).</p> </div> </td> </tr> </table> </div> </div> <div class="sect4"> <h5 id="__code_getfixtures_code"><code>getFixtures()</code></h5> <div class="paragraph"> <p>If non-<code>null</code>, this method specifies the fixture script(s) to be run on startup. This is particularly useful when developing or demoing while using an in-memory database.</p> </div> <div class="paragraph"> <p>For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><? <span class="directive">extends</span> FixtureScript>> getFixtures() { <span class="keyword">return</span> Lists.newArrayList(todoapp.fixture.demo.DemoFixture.class); }</code></pre> </div> </div> <div class="paragraph"> <p>Note that in order for fixtures to be installed it is also necessary to set the <code>isis.persistor.datanucleus.install-fixtures</code> key to <code>true</code>. This can most easily be done using the <code>getConfigurationProperties()</code> method, discussed below.</p> </div> </div> <div class="sect4"> <h5 id="__code_getconfigurationproperties_code"><code>getConfigurationProperties()</code></h5> <div class="paragraph"> <p>This method allow arbitrary other configuration properties to be overridden. One common use case is in conjunction with the <code>getFixtures()</code> method, discussed above:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> getConfigurationProperties() { <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> props = Maps.newHashMap(); props.put(<span class="string"><span class="delimiter">"</span><span class="content">isis.persistor.datanucleus.install-fixtures</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>); <span class="keyword">return</span> props; }</code></pre> </div> </div> </div> </div> <div class="sect3"> <h4 id="_bootstrapping">3.1.2. Bootstrapping</h4> <div class="paragraph"> <p>One of the primary goals of the <code>AppManifest</code> is to unify the bootstrapping of both integration tests and the webapp. This requires that the integration tests and webapp can both reference the implementation.</p> </div> <div class="paragraph"> <p>We strongly recommend using a <code>myapp-app</code> Maven module to hold the implementation of the <code>AppManifest</code>. This Maven module can then also hold dependencies which are common to both integration tests and the webapp, specifically the <code>org.apache.isis.core:isis-core-runtime</code> and the <code>org.apache.isis.core:isis-core-wrapper</code> modules.</p> </div> <div class="paragraph"> <p>We also strongly recommend that any application-layer domain services and view models (code that references persistent domain entities but that is not referenced back) is moved to this <code>myapp-app</code> module. This will allow the architectural layering of the overall application to be enforced by Maven.</p> </div> <div class="paragraph"> <p>What then remains is to update the bootstrapping code itself.</p> </div> <div class="sect4"> <h5 id="_integration_tests">Integration Tests</h5> <div class="paragraph"> <p>A <code>AppManifest.Util</code> helper class provides a number of static methods that can be used to set up configuration properties appropriate for integration testing (eg run using an in-memory database). This allows the responsibility of returning the configuration properties to belong exlusively to the <code>AppManifest</code>.</p> </div> <div class="paragraph"> <p>There are three such static methods:</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">AppManifest</span> { ... public <span class="directive">static</span> <span class="type">class</span> <span class="class">Util</span> { <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>,<span class="predefined-type">String</span>> withJavaxJdoRunInMemoryProperties(<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> map) { ... } <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>,<span class="predefined-type">String</span>> withDataNucleusProperties(<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> map) { ... } <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>,<span class="predefined-type">String</span>> withIsisIntegTestProperties(<span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> map) { ... } <i class="conum" data-value="3"></i><b>(3)</b> } }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>sets up the <code>javax.jdo.option.Connection*</code> properties so as to run against an in-memory instance of HSQLDB</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>sets up DataNucleus to automatically create the databse schema, as well as a number of other standard properties (disable persistence by reachability, support mixed case identifiers, disable level 2 cache)</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>sets up standard properties for the Apache Isis framework, most specifically to enable fixtures to be installed.</td> </tr> </table> </div> <div class="paragraph"> <p>For example, the bootstrapping code for the <a href="ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> looks something like:</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">DomainAppSystemInitializer</span> { <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> initIsft() { IsisSystemForTest isft = IsisSystemForTest.getElseNull(); <span class="keyword">if</span>(isft == <span class="predefined-constant">null</span>) { isft = <span class="keyword">new</span> IsisSystemForTest.Builder() .withLoggingAt(org.apache.log4j.Level.INFO) .with(<span class="keyword">new</span> DomainAppAppManifest() { <span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> getConfigurationProperties() { <span class="directive">final</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> map = Maps.newHashMap(); <span class="predefined-type">Util</span>.withJavaxJdoRunInMemoryProperties(map); <span class="predefined-type">Util</span>.withDataNucleusProperties(map); <span class="predefined-type">Util</span>.withIsisIntegTestProperties(map); <span class="keyword">return</span> map; } }) .build(); isft.setUpSystem(); IsisSystemForTest.set(isft); } } }</code></pre> </div> </div> <div class="paragraph"> <p>Previously the <code>IsisConfigurationJdoIntegTests</code> (subclass of <code>IsisConfiguration</code>) was provided to set up these configuration properties. This class is still supported, but is deprecated.</p> </div> </div> <div class="sect4"> <h5 id="_webapps">Webapps</h5> <div class="paragraph"> <p>To bootstrap an Apache Isis webapp (using the <a href="ugvw.html">Wicket viewer</a>), there are two choices:</p> </div> <div class="ulist"> <ul> <li> <p>either specify the <code>AppManifest</code> by overriding the <code>IsisWicketApplication#newWicketModule()</code>, eg:<br></p> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span> <span class="directive">protected</span> Module newIsisWicketModule() { <span class="directive">final</span> Module isisDefaults = <span class="local-variable">super</span>.newIsisWicketModule(); ... final Module overrides = <span class="keyword">new</span> AbstractModule() { <span class="annotation">@Override</span> <span class="directive">protected</span> <span class="type">void</span> configure() { ... bind(AppManifest.class).toInstance(<span class="keyword">new</span> MyAppAppManifest()); } }; <span class="keyword">return</span> Modules.override(isisDefaults).with(overrides); }</code></pre> </div> </div> </li> <li> <p>alternatively update <code>isis.properties</code>, using the <code>isis.appManifest</code> key to specify the <code>AppManifest</code> implementation, eg:<br></p> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="ini">isis.appManifest=domainapp.app.MyAppAppManifest</code></pre> </div> </div> </li> </ul> </div> <div class="paragraph"> <p>The first (programmatic) approach takes precedence over the second approach (configuration properties).</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>If you use the <code>org.apache.isis.WebServer</code> class to launch your application from the <a href="ugbtb.html#_ugbtb_deployment_cmd-line">command line</a>, then note that you can specify the <code>AppManifest</code> using the <code>-m</code> (or <code>--manifest</code>) flag:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="ini">java org.apache.isis.WebServer -m com.mycompany.myapp.MyAppAppManifestWithFixtures</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> <div class="sect3"> <h4 id="_subsidiary_goals">3.1.3. Subsidiary Goals</h4> <div class="paragraph"> <p>There are a number of subsidiary goals of the <code>AppManifest</code> class (though as of v1.13.0 these have not yet implemented):</p> </div> <div class="ulist"> <ul> <li> <p>Allow different integration tests to run with different manifests.</p> <div class="ulist"> <ul> <li> <p>Normally the running application is shared (on a thread-local) between integration tests. What the framework could perhaps do is to be intelligent enough to keep track of the manifest in use for each integration test and tear down the shared state if the "next" test uses a different manifest</p> </li> </ul> </div> </li> <li> <p>Provide a programmatic way to contribute elements of <code>web.xml</code>.</p> </li> <li> <p>Provide a programmatic way to configure Shiro security.</p> </li> <li> <p>Anticipate the module changes forthcoming in Java 9.</p> <div class="ulist"> <ul> <li> <p>Eventually we see that the <code>AppManifest</code> class acting as an "aggregator", with the list of modules will become Java 9 modules each advertising the types that they export.</p> </li> <li> <p>It might even be possible for <code>AppManifest</code>s to be switched on and off dynamically (eg if Java9 is compatible with OSGi, being one of the design goals).</p> </li> </ul> </div> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_super">3.2. Superclasses</h3> <div class="paragraph"> <p>This section catalogues the various convenience (non event) superclasses defined by Apache Isis. These are listed in the table below.</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 5. Convenience Superclasses</caption> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 12.5%;"> <col style="width: 12.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">API</th> <th class="tableblock halign-left valign-top">Maven Module<br> Impl’n (g: a:)</th> <th class="tableblock halign-left valign-top">Implementation</th> <th class="tableblock halign-left valign-top">Notes</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_AbstractContainedObject"><code>o.a.i.applib.</code><br> <code>AbstractContainedObject</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_AbstractDomainObject"><code>o.a.i.applib.</code><br> <code>AbstractDomainObject</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_AbstractFactoryAndRepository"><code>o.a.i.applib.</code><br> <code>AbstractFactoryAndRepository</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_AbstractService"><code>o.a.i.applib.</code><br> <code>AbstractService</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_AbstractSubscriber"><code>o.a.i.applib.</code><br> <code>AbstractSubscriber</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_AbstractViewModel"><code>o.a.i.applib.</code><br> <code>AbstractViewModel</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_FixtureScript"><code>o.a.i.applib.</code><br> <code>fixturescript</code><br> <code>FixtureScript</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_super_FixtureScripts"><code>o.a.i.applib.</code><br> <code>fixturescripts</code><br> <code>FixtureScripts</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>FixtureScriptsDefault</code> is a default implementation that is used when the alternative <a href="rgsvc.html#_rgsvc_api_FixtureScriptsSpecificationProvider"><code>FixtureScriptsSpecificationProvider</code></a> is provided (and no other implementation of <code>FixtureScripts</code> was found).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">depends on:<br> <code>ClassDiscoveryService</code></p></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_classes_super_AbstractContainedObject">3.2.1. <code>AbstractContainedObject</code></h4> <div class="paragraph"> <p>This class is a convenience superclass for domain objects and services, providing general purpose methods for interacting with the framework. These include:</p> </div> <div class="ulist"> <ul> <li> <p><code>allMatches(Query)</code> - search for all objects matching the specified <code>Query</code>.<br></p> <div class="paragraph"> <p>+ Note that this, and other similar methods (eg <code>firstMatch(…)</code>, <code>uniqueMatch(…)</code>) will automatically flush the current transactoin.</p> </div> </li> <li> <p><code>newTransientInstance(Class)</code> - to create a new instance of an object, with any services injected into it</p> </li> <li> <p><code>persistIfNotAlready(Object)</code> - to persist an object<br></p> <div class="paragraph"> <p>In fact, the object is queued up to be persisted, and is only actually persisted either when the transaction commits, or when the transaction is flushed (typically when a query is performed).</p> </div> </li> <li> <p><code>warnUser(String)</code> - generate a warning to the user</p> </li> <li> <p><code>getContainer()</code> - which returns the <code>DomainObjectContainer</code></p> </li> </ul> </div> <div class="paragraph"> <p>Each of these methods simply delegates to an equivalent method in <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>In practice we find that there’s little to gain from subclassing; it’s easier/less obscure to simply inject <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a> into a simple pojo class.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_AbstractDomainObject">3.2.2. <code>AbstractDomainObject</code></h4> <div class="paragraph"> <p>This class extends <a href="#_rgcms_classes_super_AbstractContainedObject"><code>AbstractContainedObject</code></a>, adding in convenience methods for managing the persistence lifecycle of the object instance.</p> </div> <div class="paragraph"> <p>Each of these methods, eg <code>isPersistent(…)</code>, delegates to an equivalent method in <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_AbstractFactoryAndRepository">3.2.3. <code>AbstractFactoryAndRepository</code></h4> <div class="paragraph"> <p>This class extends <a href="#_rgcms_classes_super_AbstractContainedObject"><code>AbstractContainedObject</code></a>. Its intent was to be a convenience subclass for services acting as either a repository or a factory, however note that all of the methods that it defines are now deprecated.</p> </div> <div class="paragraph"> <p>Instead, indicate that a service is repository using the <a href="rgant.html#_rgant-DomainService_repositoryFor"><code>@DomainService#repositoryFor()</code></a> attribute.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_AbstractService">3.2.4. <code>AbstractService</code></h4> <div class="paragraph"> <p>This class extends <a href="#_rgcms_classes_super_AbstractContainedObject"><code>AbstractContainedObject</code></a>, adding in an implementation of <code>getId()</code> based upon the classes name.</p> </div> <div class="paragraph"> <p>In practice there is little to gain from subclassing; simply inject <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a> for broadly equivalent functionality.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_AbstractSubscriber">3.2.5. <code>AbstractSubscriber</code></h4> <div class="paragraph"> <p>This is a convenience superclass for creating subscriber domain services on the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>. It uses <a href="rgant.html#_rgant-PostConstruct"><code>@PostConstruct</code></a> and <a href="rgant.html#_rgant-PreDestroy"><code>@PreDestroy</code></a> callbacks to automatically register/unregister itself with the <code>EventBusService</code>.</p> </div> <div class="paragraph"> <p>It’s important that subscribers register before any domain services that might emit events on the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>. For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module provides a domain service that automatically seeds certain domain entities; these will generate <a href="#_rgcms_classes_lifecycleevent">lifecycle events</a> and so any subscribers must be registered before such seed services. The easiest way to do this is to use the <a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> attribute.</p> </div> <div class="paragraph"> <p>As a convenience, the <code>AbstractSubscriber</code> specifies this attribute.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_AbstractViewModel">3.2.6. <code>AbstractViewModel</code></h4> <div class="paragraph"> <p>This class extends <a href="#_rgcms_classes_super_AbstractContainedObject"><code>AbstractContainedObject</code></a>, also implementing the <a href="#_rgcms_classes_super_ViewModel"><code>ViewModel</code></a> interface. In and of itself it provides no new behaviour.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>As an alternative, consider simply annotating the view model class with {@link org.apache.isis.applib.annotation.ViewModel}.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_FixtureScript">3.2.7. <code>FixtureScript</code></h4> <div class="paragraph"> <p>The <code>FixtureScript</code> class is an abstract class defining an API to set up data within the object store, either for integration tests or while demoing/prototyping.</p> </div> <div class="paragraph"> <p>The primary method that subclasses must implement is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">protected</span> <span class="directive">abstract</span> <span class="type">void</span> execute(<span class="directive">final</span> ExecutionContext executionContext);</code></pre> </div> </div> <div class="paragraph"> <p>In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected domain services to set up data. The provided <code>ExecutionContext</code> is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).</p> </div> <div class="paragraph"> <p>See the see the <a href="ugtst.html#_ugtst_fixture-scripts">user guide’s testing chapter</a> for further discussion on the use of fixture scripts, in particular <a href="ugtst.html#_ugtst_fixture-scripts_api-and-usage">fixture scripts' API and usage</a>.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_super_FixtureScripts">3.2.8. <code>FixtureScripts</code></h4> <div class="paragraph"> <p>This abstract class is intended to allow a domain service that can execute <a href="#_rgcms_classes_super_FixtureScript"><code>FixtureScript</code></a>s to be easily written.</p> </div> <div class="paragraph"> <p>However, it has now been deprecated; instead we recommend that the <a href="rgsvc.html#_rgsvc_spi_FixtureScriptsSpecificationProvider"><code>FixtureScriptsSpecificationProvider</code></a> service is implemented instead. The framework will then automatically use <a href="rgsvc.html#_rgsvc_api_FixtureScriptsDefault"><code>FixtureScriptsDefault</code></a> as a fallback implementation of this class.</p> </div> <div class="paragraph"> <p>See the see the <a href="ugtst.html#_ugtst_fixture-scripts">user guide’s testing chapter</a> for further discussion on the use of fixture scripts, in particular <a href="ugtst.html#_ugtst_fixture-scripts_api-and-usage">fixture scripts' API and usage</a>.</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_domainevent">3.3. Domain Event Classes</h3> <div class="paragraph"> <p>This section catalogues the various domain event classes defined by Apache Isis.</p> </div> <div class="paragraph"> <p>These events are broadcast on the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>. The domain events are broadcast as a result of being specified in the <a href="rgant.html#_rgant-Action_domainEvent"><code>@Action#domainEvent()</code></a>, <a href="rgant.html#_rgant-Property_domainEvent"><code>@Property#domainEvent()</code></a> or <a href="rgant.html#_rgant-Collection_domainEvent"><code>@Collection#domainEvent()</code></a> attributes.</p> </div> <div class="paragraph"> <p>They are listed in the table below.</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 6. Domain Event Classes</caption> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 12.5%;"> <col style="width: 12.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">API</th> <th class="tableblock halign-left valign-top">Maven Module<br> Impl’n (g: a:)</th> <th class="tableblock halign-left valign-top">Implementation</th> <th class="tableblock halign-left valign-top">Notes</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_domainevent_AbstractDomainEvent"><code>o.a.i.applib.</code><br> <code>AbstractDomainEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Superclass of the other domain events, listed below in this table.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_domainevent_ActionDomainEvent"><code>o.a.i.applib.</code><br> <code>ActionDomainEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ActionDomainEvent.Default</code> is the concrete implementation used if no <code>@Action#domainEvent</code> attribute is specified</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object’s action.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_domainevent_CollectionDomainEvent"><code>o.a.i.applib.</code><br> <code>CollectionDomainEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>CollectionDomainEvent.Default</code> is the concrete implementation used if no <code>@Collection#domainEvent</code> attribute is specified.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast whenever there is an interaction (hide/disable/validate/access) with an object’s collection.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_domainevent_PropertyDomainEvent"><code>o.a.i.applib.</code><br> <code>PropertyDomainEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>PropertyDomainEvent.Default</code> is the concrete implementation used if no <code>@Propert#domainEvent</code> attribute is specified</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast whenever there is an interaction (hide/disable/validate/access) with an object’s property.</p></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_classes_domainevent_AbstractDomainEvent">3.3.1. <code>AbstractDomainEvent</code></h4> <div class="paragraph"> <p>This class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.</p> </div> <div class="paragraph"> <p>Its immediate subclasses are:</p> </div> <div class="ulist"> <ul> <li> <p><a href="#_rgcms_classes_domainevent_ActionDomainEvent"><code>ActionDomainEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_domainevent_PropertyDomainEvent"><code>PropertyDomainEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_domainevent_CollectionDomainEvent"><code>CollectionDomainEvent</code></a></p> </li> </ul> </div> <div class="paragraph"> <p>The main purpose of the class is to define the protocol by which subscribers can influence an interaction (eg hide a collection, disable a property, validate action arguments). It class also provides a simple mechanism to allow adhoc sharing of user data between different phases.</p> </div> <div class="sect4"> <h5 id="_api_2">API</h5> <div class="paragraph"> <p>The API of the class is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">AbstractDomainEvent</span><S> <span class="directive">extends</span> java.util.EventObject { <span class="directive">public</span> Phase getEventPhase(); <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> S getSource(); <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">public</span> Identifier getIdentifier(); <i class="conum" data-value="3"></i><b>(3)</b> <span class="directive">public</span> <span class="type">void</span> hide(); <i class="conum" data-value="4"></i><b>(4)</b> <span class="directive">public</span> <span class="type">boolean</span> isHidden(); <i class="conum" data-value="5"></i><b>(5)</b> <span class="directive">public</span> <span class="type">void</span> disable(<span class="directive">final</span> <span class="predefined-type">String</span> reason); <i class="conum" data-value="6"></i><b>(6)</b> <span class="directive">public</span> <span class="type">void</span> disable(<span class="directive">final</span> TranslatableString reason); <span class="directive">public</span> <span class="predefined-type">String</span> getDisabledReason(); <i class="conum" data-value="7"></i><b>(7)</b> <span class="directive">public</span> TranslatableString getDisabledReasonTranslatable(); <span class="directive">public</span> <span class="type">boolean</span> isDisabled(); <span class="directive">public</span> <span class="type">void</span> invalidate(<span class="directive">final</span> <span class="predefined-type">String</span> reason); <i class="conum" data-value="8"></i><b>(8)</b> <span class="directive">public</span> <span class="type">void</span> invalidate(<span class="directive">final</span> TranslatableString reason); <span class="directive">public</span> <span class="predefined-type">String</span> getInvalidityReason(); <i class="conum" data-value="9"></i><b>(9)</b> <span class="directive">public</span> TranslatableString getInvalidityReasonTranslatable(); <span class="directive">public</span> <span class="type">boolean</span> isInvalid(); <span class="directive">public</span> <span class="type">void</span> veto(<span class="directive">final</span> <span class="predefined-type">String</span> reason, <span class="directive">final</span> <span class="predefined-type">Object</span>... args); <i class="conum" data-value="10"></i><b>(10)</b> <span class="directive">public</span> <span class="type">void</span> veto(<span class="directive">final</span> TranslatableString translatableReason); <span class="directive">public</span> <span class="predefined-type">Object</span> get(<span class="predefined-type">Object</span> key); <i class="conum" data-value="11"></i><b>(11)</b> <span class="directive">public</span> <span class="type">void</span> put(<span class="predefined-type">Object</span> key, <span class="predefined-type">Object</span> value); }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>Whether the framework is checking visibility, enablement, validity or actually executing (invoking action, editing property), as per the <code>Phase</code> enum (defined below).</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>The domain object raising this event</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>Identifier of the action, property or collection being interacted with.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>API for subscribers to hide the member</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>Used by the framework to determine if the member should be hidden (not rendered)</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>API for subscribers to disable the member, specifying the reason why (possibly translated)</td> </tr> <tr> <td><i class="conum" data-value="7"></i><b>7</b></td> <td>Used by the framework to determine whether the member should be disabled (greyed out) when rendered.</td> </tr> <tr> <td><i class="conum" data-value="8"></i><b>8</b></td> <td>API for subscribers to invalidate an interaction, eg invalid arguments to an action</td> </tr> <tr> <td><i class="conum" data-value="9"></i><b>9</b></td> <td>Used by the framework to determine whether the interaction is invalid and should be blocked (eg pressing OK shows message)</td> </tr> <tr> <td><i class="conum" data-value="10"></i><b>10</b></td> <td>Convenience API for subscribers to veto; will automatically call either <code>hide()</code>, <code>disable(…)</code> or <code>invalidate(…)</code> based on the phase</td> </tr> <tr> <td><i class="conum" data-value="11"></i><b>11</b></td> <td>Mechanism to allow subscribers to share arbitrary information between phases. One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.</td> </tr> </table> </div> <div class="paragraph"> <p>The referenced <code>Phase</code> enum is in turn:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">enum</span> Phase { HIDE, DISABLE, VALIDATE, EXECUTING, EXECUTED; <span class="directive">public</span> <span class="type">boolean</span> isValidatingOrLater(); <i class="conum" data-value="1"></i><b>(1)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>The significance being that at this point the proposed values/arguments are known, and so the event can be fully populated.</td> </tr> </table> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_domainevent_ActionDomainEvent">3.3.2. <code>ActionDomainEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_domainevent_AbstractDomainEvent"><code>AbstractDomainEvent</code></a> for actions.</p> </div> <div class="paragraph"> <p>The class has a number of responsibilities (in addition to those it inherits):</p> </div> <div class="ulist"> <ul> <li> <p>capture the target object being interacted with</p> </li> <li> <p>capture the arguments for each of the action’s parameters</p> </li> <li> <p>provide selected metadata about the action parameters from the metamodel (names, types)</p> </li> <li> <p>link back to the <a href="rgsvc.html#_rgsvc_api_CommandContext"><code>CommandContext</code></a> service’s <code>Command</code> object</p> </li> </ul> </div> <div class="paragraph"> <p>The class itself is instantiated automatically by the framework whenever interacting with a rendered object’s action.</p> </div> <div class="sect4"> <h5 id="_api_3">API</h5> <div class="paragraph"> <p>The API of the class is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">ActionDomainEvent</span><S> <span class="directive">extends</span> AbstractDomainEvent<S> { <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Default</span> <span class="directive">extends</span> ActionDomainEvent<<span class="predefined-type">Object</span>> { ... } <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Noop</span> <span class="directive">extends</span> ActionDomainEvent<<span class="predefined-type">Object</span>> { ... } <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Doop</span> <span class="directive">extends</span> ActionDomainEvent<<span class="predefined-type">Object</span>> { ... } <i class="conum" data-value="3"></i><b>(3)</b> <span class="annotation">@Deprecated</span> <span class="directive">public</span> Command getCommand(); <i class="conum" data-value="4"></i><b>(4)</b> <span class="directive">public</span> SemanticsOf getSemantics(); <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">String</span>> getParameterNames(); <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Class</span><?>> getParameterTypes(); <span class="directive">public</span> <span class="predefined-type">Object</span> getMixedIn(); <i class="conum" data-value="5"></i><b>(5)</b> <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Object</span>> getArguments(); <i class="conum" data-value="6"></i><b>(6)</b> <span class="directive">public</span> <span class="predefined-type">Object</span> getReturnValue(); <i class="conum" data-value="7"></i><b>(7)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>The <code>Default</code> nested static class is the default for the <a href="rgant.html#_rgant_Action_domainEvent"><code>@Action#domainEvent()</code></a> annotation attribute. Whether this raises an event or not depends upon the <code>isis.reflector.facet.actionAnnotation.domainEvent.postForDefault</code> configuration property.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>The <code>Noop</code> class is provided as a convenience to indicate that an event should <em>not</em> be posted (irrespective of the configuration property setting).</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>Similarly, the <code>Doop</code> class is provided as a convenience to indicate that an event <em>should</em> be raised (irrespective of the configuration property setting).</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>Deprecated, use <a href="rgsvc.html#_rgsvc_api_CommandContext"><code>CommandContext</code></a> or (better) <a href="rgsvc.html#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a>instead.</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>Populated only for mixins; holds the underlying domain object that the mixin contributes to.</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>The arguments being used to invoke the action; populated during validate phase and subsequent phases.</td> </tr> <tr> <td><i class="conum" data-value="7"></i><b>7</b></td> <td>The value returned by the action; populated only in the executed phase.</td> </tr> </table> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_domainevent_CollectionDomainEvent">3.3.3. <code>CollectionDomainEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_domainevent_AbstractDomainEvent"><code>AbstractDomainEvent</code></a> for collections.</p> </div> <div class="paragraph"> <p>The class has a couple of responsibilities (in addition to those it inherits):</p> </div> <div class="ulist"> <ul> <li> <p>capture the target object being interacted with</p> </li> <li> <p>indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)</p> </li> <li> <p>capture the object reference being added or removed</p> </li> </ul> </div> <div class="paragraph"> <p>The class itself is instantiated automatically by the framework whenever interacting with a rendered object’s collection.</p> </div> <div class="sect4"> <h5 id="_api_4">API</h5> <div class="paragraph"> <p>The API of the class is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">CollectionDomainEvent</span><S,T> <span class="directive">extends</span> AbstractDomainEvent<S> { <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Default</span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">extends</span> CollectionDomainEvent<<span class="predefined-type">Object</span>, <span class="predefined-type">Object</span>> { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Noop</span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">extends</span> CollectionDomainEvent<<span class="predefined-type">Object</span>, <span class="predefined-type">Object</span>> { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Doop</span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="directive">extends</span> CollectionDomainEvent<<span class="predefined-type">Object</span>, <span class="predefined-type">Object</span>> { ... } <span class="directive">public</span> T getValue(); <i class="conum" data-value="4"></i><b>(4)</b> <span class="directive">public</span> Of getOf(); <i class="conum" data-value="5"></i><b>(5)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>The <code>Default</code> nested static class is the default for the <a href="rgant.html#_rgant_Collection_domainEvent"><code>@Collection#domainEvent()</code></a> annotation attribute. Whether this raises an event or not depends upon the <code>isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault</code> configuration property.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>The <code>Noop</code> class is provided as a convenience to indicate that an event should <em>not</em> be posted (irrespective of the configuration property setting).</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>Similarly, the <code>Doop</code> class is provided as a convenience to indicate that an event <em>should</em> be raised (irrespective of the configuration property setting).</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the object being added or removed</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>whether this is to add or to remove</td> </tr> </table> </div> <div class="paragraph"> <p>where the <code>Of</code> enum indicates in turn how the collection is being interacted with:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">static</span> <span class="type">enum</span> Of { ACCESS, <i class="conum" data-value="1"></i><b>(1)</b> ADD_TO, <i class="conum" data-value="2"></i><b>(2)</b> REMOVE_FROM <i class="conum" data-value="3"></i><b>(3)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>collection is being rendered; set during for hide and disable phases</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>collection is being added to; set for validate, executing and executed phases</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>or, collection is being removed from; set for validate, executing and executed phases</td> </tr> </table> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_domainevent_PropertyDomainEvent">3.3.4. <code>PropertyDomainEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_domainevent_AbstractDomainEvent"><code>AbstractDomainEvent</code></a> for properties.</p> </div> <div class="paragraph"> <p>The class has a couple of responsibilities (in addition to those it inherits):</p> </div> <div class="ulist"> <ul> <li> <p>capture the target object being interacted with</p> </li> <li> <p>capture the old and new values of the property</p> </li> </ul> </div> <div class="paragraph"> <p>The class itself is instantiated automatically by the framework whenever interacting with a rendered object’s property.</p> </div> <div class="sect4"> <h5 id="_api_5">API</h5> <div class="paragraph"> <p>The API of the class is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PropertyDomainEvent</span><S,T> <span class="directive">extends</span> AbstractDomainEvent<S> { <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Default</span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">extends</span> PropertyDomainEvent<<span class="predefined-type">Object</span>, <span class="predefined-type">Object</span>> { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Noop</span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="directive">extends</span> PropertyDomainEvent<<span class="predefined-type">Object</span>, <span class="predefined-type">Object</span>> { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Doop</span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="directive">extends</span> PropertyDomainEvent<<span class="predefined-type">Object</span>, <span class="predefined-type">Object</span>> { ... } <span class="directive">public</span> T getOldValue(); <i class="conum" data-value="4"></i><b>(4)</b> <span class="directive">public</span> T getNewValue(); <i class="conum" data-value="5"></i><b>(5)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>The <code>Default</code> nested static class is the default for the <a href="rgant.html#_rgant_Property_domainEvent"><code>@Property#domainEvent()</code></a> annotation attribute. Whether this raises an event or not depends upon the <code>isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault</code> configuration property.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>The <code>Noop</code> class is provided as a convenience to indicate that an event should <em>not</em> be posted (irrespective of the configuration property setting).</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>Similarly, the <code>Doop</code> class is provided as a convenience to indicate that an event <em>should</em> be raised (irrespective of the configuration property setting).</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>The pre-modification value of the property; populated at validate and subsequent phases.</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>The proposed (post-modification) value of the property; populated at validate and subsequent phases</td> </tr> </table> </div> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_uievent">3.4. UI Event Classes</h3> <div class="paragraph"> <p>This section catalogues the various UI event classes defined by Apache Isis.</p> </div> <div class="paragraph"> <p>These events are broadcast on the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>. The domain events are broadcast as a result of being specified in the <a href="rgant.html#_rgant-DomainObjectLayout_titleUiEvent"><code>@DomainObjectLayout#titleUiEvent()</code></a>, <a href="rgant.html#_rgant-DomainObjectLayout_iconUiEvent"><code>@DomainObjectLayout#iconUiEvent()</code></a> or <a href="rgant.html#_rgant-DomainObjectLayout_cssClassUiEvent"><code>@DomainObjectLayout#cssClassUiEvent()</code></a> attributes.</p> </div> <div class="paragraph"> <p>They are listed in the table below.</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 7. UI Event Classes</caption> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 12.5%;"> <col style="width: 12.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">API</th> <th class="tableblock halign-left valign-top">Maven Module<br> Impl’n (g: a:)</th> <th class="tableblock halign-left valign-top">Implementation</th> <th class="tableblock halign-left valign-top">Notes</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_uievent_TitleUiEvent"><code>o.a.i.applib.</code><br> <code>TitleUiEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>TitleUiEvent.Default</code> is the concrete implementation used if no <code>@DomainObjectLayout#titleUiEvent</code> attribute is specified</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast whenever there is a requirement to obtain a title for a domain object. Note that if the domain object defines its own <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> supporting method, or has <a href="rgant.html#_rgant-Title"><code>@Title</code></a> annotation(s) on its properties, then these will take precedence.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_uievent_IconUiEvent"><code>o.a.i.applib.</code><br> <code>IconUiEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>IconUiEvent.Default</code> is the concrete implementation used if no <code>@DomainObjectLayout#iconUiEvent</code> attribute is specified</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object. Note that if the domain object defines its own <a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a> supporting method, or if it has the <a href="rgant.html#_rgant-DomainObjectLayout"><code>@DomainObjectLayout#cssClassFa()</code></a> attribute, then these will take precedence.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_uievent_CssClassUiEvent"><code>o.a.i.applib.</code><br> <code>CssClassUiEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>CssClassUiEvent.Default</code> is the concrete implementation used if no <code>@DomainObjectLayout#cssClassUiEvent</code> attribute is specified</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object. Note that if the domain object defines its own <a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a> supporting method then this will take precedence.</p></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_classes_uievent_TitleUiEvent">3.4.1. <code>TitleUiEvent</code></h4> <div class="paragraph"> <p>This event class represents a request to obtain the title of a domain object. The class has a number of responsibilities:</p> </div> <div class="ulist"> <ul> <li> <p>capture the target object being interacted with</p> </li> <li> <p>capture the title, if any, as specified to one of the subscribers</p> </li> </ul> </div> <div class="paragraph"> <p>The class itself is instantiated automatically by the framework whenever interacting with a rendered object’s action.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>If the domain object defines its own <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> supporting method, or has <a href="rgant.html#_rgant-Title"><code>@Title</code></a> annotation(s) on its properties, then these will take precedence.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_uievent_IconUiEvent">3.4.2. <code>IconUiEvent</code></h4> <div class="paragraph"> <p>This event class represents a request to obtain the icon (or rather, name of icon) of a domain object. The class has a number of responsibilities:</p> </div> <div class="ulist"> <ul> <li> <p>capture the target object being interacted with</p> </li> <li> <p>capture the icon (name), if any, as specified to one of the subscribers</p> </li> </ul> </div> <div class="paragraph"> <p>The class itself is instantiated automatically by the framework whenever interacting with a rendered object’s action.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>If the domain object defines its own <a href="#_rgcms_methods_reserved_iconName"><code>iconName()</code></a> supporting method, or if it has the <a href="rgant.html#_rgant-DomainObjectLayout"><code>@DomainObjectLayout#cssClassFa()</code></a> attribute, then these will take precedence.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_uievent_CssClassUiEvent">3.4.3. <code>CssClassUiEvent</code></h4> <div class="paragraph"> <p>This event class represents a request to obtain the a CSS class hint of a domain object. The class has a number of responsibilities:</p> </div> <div class="ulist"> <ul> <li> <p>capture the target object being interacted with</p> </li> <li> <p>capture the CSS class, if any, as specified to one of the subscribers</p> </li> </ul> </div> <div class="paragraph"> <p>The class itself is instantiated automatically by the framework whenever interacting with a rendered object’s action.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>if the domain object defines its own <a href="#_rgcms_methods_reserved_cssClass"><code>cssClass()</code></a> supporting method then this will take precedence.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_lifecycleevent">3.5. Lifecycle Events</h3> <div class="paragraph"> <p>This section catalogues the various lifecycle event classes defined by Apache Isis. These events are fired automatically when a domain object is loaded, created, updated and so forth.</p> </div> <div class="paragraph"> <p>The lifecycle event classes are listed in the table below:</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 8. Lifecycle Event Classes</caption> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 12.5%;"> <col style="width: 12.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">API</th> <th class="tableblock halign-left valign-top">Maven Module<br> Impl’n (g: a:)</th> <th class="tableblock halign-left valign-top">Implementation</th> <th class="tableblock halign-left valign-top">Notes</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>o.a.i.applib.</code><br> <code>AbstractLifecycleEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Superclass of the other lifecycle events, listed below in this table.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectCreatedDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectCreatedEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectCreatedEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object is first instantiated using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-creation-api"><code>DomainObjectContainer</code></a>'s <code>#newTransientInstance(…)</code> method.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectLoadedDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectLoadedEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectLoadedEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object is retrieved from the database.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectPersistedDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectPersistedEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectPersistedEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object is first saved (inserted) into the database using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#persist(…)</code> method.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectPersistingDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectPersistingEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectPersistingEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object is about to be saved (inserted) into the database using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#persist(…)</code> method.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectRemovingDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectRemovingEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectRemovingEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object is about to be deleted from the database using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#remove(…)</code> method.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectUpdatedDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectUpdatedEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectUpdatedEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object has just been updated in the database. This is done either explicitly when the current transaction is flushed using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#flush(…)</code> method, else is done implicitly when the transaction commits at the end of the user request.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgcms_classes_lifecycleevent_ObjectUpdatingDomainEvent"><code>o.a.i.applib.</code><br> <code>ObjectUpdatingEvent</code></a></p></td> <td class="tableblock halign-left valign-top"><div><div class="paragraph"> <p><code>o.a.i.core</code><br> <code>services.eventbus</code><br> <code>isis-core-applib</code></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(abstract class).<br> <code>ObjectUpdatingEvent.Default</code> is the concrete implementation that is used.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Broadcast when an object is about to be updated in the database. This is done either explicitly when the current transaction is flushed using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#flush(…)</code> method, else is done implicitly when the transaction commits at the end of the user request.</p></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_AbstractLifecycleEvent">3.5.1. <code>AbstractLifecycleEvent</code></h4> <div class="paragraph"> <p>This class is the superclass for all lifecycle events that are raised by the framework when loading, saving, updating or deleting objects from the database.</p> </div> <div class="paragraph"> <p>Its immediate subclasses are:</p> </div> <div class="ulist"> <ul> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectCreatedEvent"><code>ObjectCreatedEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectLoadedEvent"><code>ObjectLoadedEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectPersistedEvent"><code>ObjectPersistedEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectPersistingEvent"><code>ObjectPersistingEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectRemovingEvent"><code>ObjectRemovingEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent"><code>ObjectUpdatedEvent</code></a></p> </li> <li> <p><a href="#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent"><code>ObjectUpdatingEvent</code></a></p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectCreatedEvent">3.5.2. <code>ObjectCreatedEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object is first instantiated using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-creation-api"><code>DomainObjectContainer</code></a>'s <code>#newTransientInstance(…)</code> method.</p> </div> <div class="paragraph"> <p><code>ObjectCreatedEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectLoadedEvent">3.5.3. <code>ObjectLoadedEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object is retrieved from the database.</p> </div> <div class="paragraph"> <p><code>ObjectLoadedEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectPersistedEvent">3.5.4. <code>ObjectPersistedEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object is first saved (inserted) into the database using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#persist(…)</code> method.</p> </div> <div class="paragraph"> <p><code>ObjectPersistedEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectPersistingEvent">3.5.5. <code>ObjectPersistingEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object is about to be saved (inserted) into the database using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#persist(…)</code> method.</p> </div> <div class="paragraph"> <p><code>ObjectPersistingEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectRemovingEvent">3.5.6. <code>ObjectRemovingEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object is about to be deleted from the database using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#remove(…)</code> method.</p> </div> <div class="paragraph"> <p><code>ObjectRemovingEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectUpdatedEvent">3.5.7. <code>ObjectUpdatedEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object has just been updated in the database. This is done either explicitly when the current transaction is flushed using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#flush(…)</code> method, else is done implicitly when the transaction commits at the end of the user request.</p> </div> <div class="paragraph"> <p><code>ObjectUpdatedEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_lifecycleevent_ObjectUpdatingEvent">3.5.8. <code>ObjectUpdatingEvent</code></h4> <div class="paragraph"> <p>Subclass of <a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent"><code>AbstractLifecycleEvent</code></a>, broadcast when an object is about to be updated in the database. This is done either explicitly when the current transaction is flushed using the <a href="rgsvc.html#_rgsvc_api_DomainObjectContainer_object-persistence-api"><code>DomainObjectContainer</code></a>'s <code>#flush(…)</code> method, else is done implicitly when the transaction commits at the end of the user request.</p> </div> <div class="paragraph"> <p><code>ObjectUpdatingEvent.Default</code> is the concrete implementation that is used.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>In the future this may be generalized to allow arbitrary subclasses to be broadcast, see ISIS-803.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_value-types">3.6. Value Types</h3> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> TODO </td> </tr> </table> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 9. JDK Classes</caption> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Type</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Boolean</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Character</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Double</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Float</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Integer</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Long</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.Short</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.lang.String</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.math.BigDecimal</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.math.BigInteger</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.sql.Date</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.sql.Time</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.sql.Timestamp</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>java.util.Date</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 10. JodaTime classes</caption> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Type</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.joda.time.DateTime</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.joda.time.LocalDateTime</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.joda.time.LocalDate</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all spread"> <caption class="title">Table 11. Isis Applib classes</caption> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Type</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>o.a.i.applib.value.</code><br> <code>Blob</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>o.a.i.applib.value.</code><br> <code>Clob</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>o.a.i.applib.value.</code><br> <code>Color</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>o.a.i.applib.value.</code><br> <code>Money</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>o.a.i.applib.value.</code><br> <code>Password</code></p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="sect3"> <h4 id="_rgcms_classes_value-types_Blob">3.6.1. <code>Blob</code></h4> <div class="paragraph"> <p><code>Blob</code> (in the <code>org.apache.isis.applib.value</code> package) is a value type defined by the Apache Isis framework to represent a binary large object. Conceptually you can consider it as a set of bytes (a picture, a video etc), though in fact it wraps three pieces of information:</p> </div> <div class="ulist"> <ul> <li> <p>the set of bytes</p> </li> <li> <p>a name</p> </li> <li> <p>a mime type.</p> </li> </ul> </div> <div class="paragraph"> <p>This is reflected in the class' constructors and properties:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">Blob</span> ... { ... public <span class="predefined-type">Blob</span>(<span class="predefined-type">String</span> name, <span class="predefined-type">String</span> primaryType, <span class="predefined-type">String</span> subtype, <span class="type">byte</span><span class="type">[]</span> bytes) { ... } <span class="directive">public</span> <span class="predefined-type">Blob</span>(<span class="predefined-type">String</span> name, <span class="predefined-type">String</span> mimeTypeBase, <span class="type">byte</span><span class="type">[]</span> bytes) { ... } <span class="directive">public</span> <span class="predefined-type">Blob</span>(<span class="predefined-type">String</span> name, MimeType mimeType, <span class="type">byte</span><span class="type">[]</span> bytes) { ... } ... public <span class="predefined-type">String</span> getName() { ... } <span class="directive">public</span> MimeType getMimeType() { ... } <span class="directive">public</span> <span class="type">byte</span><span class="type">[]</span> getBytes() { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>Properties of this type can be mapped to JDO/DataNucleus using:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Persistent(defaultFetchGroup=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>, columns = { <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">someImage_name</span><span class="delimiter">"</span></span>), <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">someImage_mimetype</span><span class="delimiter">"</span></span>), <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">someImage_bytes</span><span class="delimiter">"</span></span>, jdbcType = <span class="string"><span class="delimiter">"</span><span class="content">BLOB</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">LONGVARBINARY</span><span class="delimiter">"</span></span>) }) <span class="directive">private</span> <span class="predefined-type">Blob</span> someImage;</code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>For character large objects, use <a href="#_rgcms_classes_value-types_Clob]"><code>Clob</code></a> value type.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_value-types_Clob">3.6.2. <code>Clob</code></h4> <div class="paragraph"> <p><code>Clob</code> (in the <code>org.apache.isis.applib.value</code> package) is a value type defined by the Apache Isis framework to represent a character large object. Conceptually you can consider it as a set of characters (an RTF or XML document, for example), though in fact it wraps three pieces of information:</p> </div> <div class="ulist"> <ul> <li> <p>the set of characters</p> </li> <li> <p>a name</p> </li> <li> <p>a mime type.</p> </li> </ul> </div> <div class="paragraph"> <p>This is reflected in the class' constructors and properties:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">Clob</span> ... { ... public <span class="predefined-type">Clob</span>(<span class="predefined-type">String</span> name, <span class="predefined-type">String</span> primaryType, <span class="predefined-type">String</span> subType, <span class="type">char</span><span class="type">[]</span> chars) { ... } <span class="directive">public</span> <span class="predefined-type">Clob</span>(<span class="predefined-type">String</span> name, <span class="predefined-type">String</span> mimeTypeBase, <span class="type">char</span><span class="type">[]</span> chars) { ... } <span class="directive">public</span> <span class="predefined-type">Clob</span>(<span class="predefined-type">String</span> name, MimeType mimeType, <span class="type">char</span><span class="type">[]</span> chars) { ... } <span class="directive">public</span> <span class="predefined-type">Clob</span>(<span class="predefined-type">String</span> name, <span class="predefined-type">String</span> primaryType, <span class="predefined-type">String</span> subType, <span class="predefined-type">CharSequence</span> chars) { ... } <span class="directive">public</span> <span class="predefined-type">Clob</span>(<span class="predefined-type">String</span> name, <span class="predefined-type">String</span> mimeTypeBase, <span class="predefined-type">CharSequence</span> chars) { ... } <span class="directive">public</span> <span class="predefined-type">Clob</span>(<span class="predefined-type">String</span> name, MimeType mimeType, <span class="predefined-type">CharSequence</span> chars) { ... } ... public <span class="predefined-type">String</span> getName() { ... } <span class="directive">public</span> MimeType getMimeType() { ... } <span class="directive">public</span> <span class="predefined-type">CharSequence</span> getChars() { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>Properties of this type can be mapped to JDO/DataNucleus using:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Persistent(defaultFetchGroup=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>, columns = { <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">someClob_name</span><span class="delimiter">"</span></span>), <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">someClob_mimetype</span><span class="delimiter">"</span></span>), <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">someClob_chars</span><span class="delimiter">"</span></span>, jdbcType = <span class="string"><span class="delimiter">"</span><span class="content">CLOB</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">LONGVARCHAR</span><span class="delimiter">"</span></span>) }) <span class="directive">private</span> <span class="predefined-type">Clob</span> someClob;</code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>For binary large objects, use <a href="#_rgcms_classes_value-types_Blob]"><code>Blob</code></a> value type.</p> </div> </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_value-types_Color">3.6.3. <code>Color</code></h4> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> TODO - the <code>org.apache.isis.applib.value.Color</code> class. </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_value-types_Money">3.6.4. <code>Money</code></h4> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> TODO - the <code>org.apache.isis.applib.value.Money</code> class. </td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_value-types_Password">3.6.5. <code>Password</code></h4> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> TODO </td> </tr> </table> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_utility">3.7. Applib Utility Classes</h3> <div class="paragraph"> <p>The <code>org.apache.isis.applib.util</code> package has a number of simple utility classes designed to simplify the coding of some common tasks.</p> </div> <div class="sect3"> <h4 id="_rgcms_classes_utility_Enums">3.7.1. <code>Enums</code></h4> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> TODO </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">final</span> <span class="type">class</span> <span class="class">Enums</span> { <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">String</span> getFriendlyNameOf(<span class="predefined-type">Enum</span><?> anEnum) { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">String</span> getFriendlyNameOf(<span class="predefined-type">String</span> anEnumName) { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">String</span> getEnumNameFromFriendly(<span class="predefined-type">String</span> anEnumFriendlyName) { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">String</span> enumToHttpHeader(<span class="directive">final</span> <span class="predefined-type">Enum</span><?> anEnum) { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">String</span> enumNameToHttpHeader(<span class="directive">final</span> <span class="predefined-type">String</span> name) { ... } <span class="directive">public</span> <span class="directive">static</span> <span class="predefined-type">String</span> enumToCamelCase(<span class="directive">final</span> <span class="predefined-type">Enum</span><?> anEnum) { ... } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_utility_ObjectContracts">3.7.2. <code>ObjectContracts</code></h4> <div class="paragraph"> <p>The <code>ObjectContracts</code> test provides a series of methods to make it easy for your domain objects to:</p> </div> <div class="ulist"> <ul> <li> <p>implement <code>Comparable</code> (eg so can be stored in <code>java.util.SortedSet</code>s)</p> </li> <li> <p>implement <code>toString()</code></p> </li> <li> <p>implement <code>equals()</code></p> </li> <li> <p>implement <code>hashCode()</code></p> </li> </ul> </div> <div class="paragraph"> <p>For example:</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">ToDoItem</span> <span class="directive">implements</span> <span class="predefined-type">Comparable</span><ToDoItem> { <span class="directive">public</span> <span class="type">boolean</span> isComplete() { ... } <span class="directive">public</span> LocalDate getDueBy() { ... } <span class="directive">public</span> <span class="predefined-type">String</span> getDescription() { ... } <span class="directive">public</span> <span class="predefined-type">String</span> getOwnedBy() { ... } <span class="directive">public</span> <span class="type">int</span> compareTo(<span class="directive">final</span> ToDoItem other) { <span class="keyword">return</span> ObjectContracts.compare(<span class="local-variable">this</span>, other, <span class="string"><span class="delimiter">"</span><span class="content">complete</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">dueBy</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">description</span><span class="delimiter">"</span></span>); } <span class="directive">public</span> <span class="predefined-type">String</span> toString() { <span class="keyword">return</span> ObjectContracts.toString(<span class="local-variable">this</span>, <span class="string"><span class="delimiter">"</span><span class="content">description</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">complete</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">dueBy</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">ownedBy</span><span class="delimiter">"</span></span>); } }</code></pre> </div> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>Note that <code>ObjectContracts</code> makes heavy use of Java Reflection. While it’s great to get going quickly in prototyping, we recommend you use your IDE to code generate implementations of these methods for production code.</p> </div> <div class="paragraph"> <p>Moreover (and perhaps even more importantly) <code>ObjectContracts</code> implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities (More detail below).</p> </div> <div class="paragraph"> <p>We therefore recommend that you disable persistence-by-reachability by adding:</p> </div> <div class="listingblock"> <div class="title">persistor_datanucleus.properties</div> <div class="content"> <pre class="CodeRay highlight"><code data-lang="ini">isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false</code></pre> </div> </div> </td> </tr> </table> </div> <div class="sect4"> <h5 id="_the_issue_in_more_detail">The issue in more detail</h5> <div class="paragraph"> <p>Consider the <a href="http://yuml.me/edit/742ad446">entities</a>:</p> </div> <div class="imageblock"> <div class="content"> <a class="image" href="images/reference-classes/issue-in-more-detail.png"><img src="images/reference-classes/issue-in-more-detail.png" alt="issue in more detail"></a> </div> </div> <div class="paragraph"> <p>In the course of a transaction, the <code>Agreement</code> entity is loaded into memory (not necessarily modified), and then new <code>AgreementRole</code>s are associated to it.</p> </div> <div class="paragraph"> <p>All these entities implement <code>Comparable</code> using <code>ObjectContracts</code>, so that the implementation of <code>AgreementRole</code>'s (simplified) is:</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">AgreementRole</span> { ... public <span class="type">int</span> compareTo(AgreementRole other) { <span class="keyword">return</span> ObjectContracts.compareTo(<span class="local-variable">this</span>, other, <span class="string"><span class="delimiter">"</span><span class="content">agreement</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">startDate</span><span class="delimiter">"</span></span>,<span class="string"><span class="delimiter">"</span><span class="content">party</span><span class="delimiter">"</span></span>); } ... }</code></pre> </div> </div> <div class="paragraph"> <p>while <code>Agreement</code>'s is implemented 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">Agreement</span> { ... public <span class="type">int</span> compareTo(Agreement other) { <span class="keyword">return</span> ObjectContracts.compareTo(<span class="local-variable">this</span>, other, <span class="string"><span class="delimiter">"</span><span class="content">reference</span><span class="delimiter">"</span></span>); } ... }</code></pre> </div> </div> <div class="paragraph"> <p>and <code>Party</code>'s is similarly implemented 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">Party</span> { ... public <span class="type">int</span> compareTo(Party other) { <span class="keyword">return</span> ObjectContracts.compareTo(<span class="local-variable">this</span>, other, <span class="string"><span class="delimiter">"</span><span class="content">reference</span><span class="delimiter">"</span></span>); } ... }</code></pre> </div> </div> <div class="paragraph"> <p>DataNucleus’s persistence-by-reachability algorithm adds the <code>AgreementRole</code>s into a <code>SortedSet</code>, which causes <code>AgreementRole#compareTo()</code> to fire:</p> </div> <div class="ulist"> <ul> <li> <p>the evaluation of the "agreement" property delegates back to the <code>Agreement</code>, whose own <code>Agreement#compareTo()</code> uses the scalar <code>reference</code> property. As the <code>Agreement</code> is already in-memory, this does not trigger any further database queries</p> </li> <li> <p>the evaluation of the "startDate" property is just a scalar property of the <code>AgreementRole</code>, so will already in-memory</p> </li> <li> <p>the evaluation of the "party" property delegates back to the <code>Party</code>, whose own <code>Party#compareTo()</code> requires the uses the scalar <code>reference</code> property. However, since the <code>Party</code> is not yet in-memory, using the <code>reference</code> property triggers a database query to "rehydrate" the <code>Party</code> instance.</p> </li> </ul> </div> <div class="paragraph"> <p>In other words, figuring out whether <code>AgreementRole</code> is comparable requires the persistence-by-reachability algorithm to run, causing the adjacent associated entity <code>Party</code> to also be retrieved.</p> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_utility_Reasons">3.7.3. <code>Reasons</code></h4> <div class="paragraph"> <p>There are two different classes provided to help build reasons returned by <code>disableXxX()</code> and <code>validateXxx()</code> methods:</p> </div> <div class="ulist"> <ul> <li> <p>the <code>org.apache.isis.applib.util.ReasonBuffer</code> helper class</p> </li> <li> <p>the <code>org.apache.isis.applib.util.Reasons</code> helper class</p> </li> </ul> </div> <div class="paragraph"> <p>For example:</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">Customer</span> { ... public <span class="predefined-type">String</span> validatePlaceOrder(Product p, <span class="type">int</span> quantity) { <span class="keyword">return</span> Reasons.coalesce( whetherCustomerBlacklisted(<span class="local-variable">this</span>), whetherProductOutOfStock(p) ); } }</code></pre> </div> </div> <div class="paragraph"> <p>Which you use (if any) is up to you.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_utility_TitleBuffer">3.7.4. <code>TitleBuffer</code></h4> <div class="paragraph"> <p>The <code>TitleBuffer</code> utility class is intended to make it easy to construct title strings (returned from the <a href="#_rgcms_methods_reserved_title"><code>title()</code></a> method).</p> </div> <div class="paragraph"> <p>For example, it has overloaded versions of methods called <code>append()</code> and <code>concat()</code>.</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_spec">3.8. Specification pattern</h3> <div class="paragraph"> <p>The interfaces and classes listed in this chapter provide support for the <code>Specification</code> pattern, as described in Eric Evans' book <em>Domain Driven Design</em>, p224.</p> </div> <div class="paragraph"> <p>Apache Isis will automatically apply such specifications as validation rules on properties (as per <a href="rgant.html#_rgant-Property_mustSatisfy"><code>@Property#mustSatisfy()</code></a>) and on action parameters (as per <a href="rgant.html#_rgant-Parameter_mustSatisfy"><code>@Parameter#mustSatisfy()</code></a>).</p> </div> <div class="sect3"> <h4 id="__code_specification_code">3.8.1. <code>Specification</code></h4> <div class="paragraph"> <p>The heart of the support for this pattern is the <code>Specification</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">Specification</span> { <span class="directive">public</span> <span class="predefined-type">String</span> satisfies(<span class="predefined-type">Object</span> obj); <i class="conum" data-value="1"></i><b>(1)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>if returns <code>null</code>, then the constraint is satisfies; otherwise returns the reason why the constraint has not been satisfied.</td> </tr> </table> </div> <div class="paragraph"> <p>For example:</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">StartWithCapitalLetterSpecification</span> <span class="directive">implements</span> Specification { <span class="directive">public</span> <span class="predefined-type">String</span> satisfies(<span class="predefined-type">Object</span> proposedObj) { <span class="predefined-type">String</span> proposed = (<span class="predefined-type">String</span>)proposedObj; <i class="conum" data-value="1"></i><b>(1)</b> <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="delimiter">"</span></span>.equals(proposed) ? <span class="string"><span class="delimiter">"</span><span class="content">Empty string</span><span class="delimiter">"</span></span> : !<span class="predefined-type">Character</span>.isUpperCase(proposed.charAt(<span class="integer">0</span>)) ? <span class="string"><span class="delimiter">"</span><span class="content">Does not start with a capital letter</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } } <span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> { <span class="annotation">@Property</span>(mustSatisfy=StartWithCapitalLetterSpecification.class) <span class="directive">public</span> <span class="predefined-type">String</span> getFirstName() { ... } ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>this ugly cast can be avoided using some of the other classes available; see below.</td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="__code_specification2_code">3.8.2. <code>Specification2</code></h4> <div class="paragraph"> <p>The <code>Specification2</code> interface extends the <code>Specification</code> API to add support for i18n. This is done by defining an additional method that returns a <a href="#_rgcms_classes_i18n_TranslatableString">translatable string</a>:</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">Specification2</span> <span class="directive">extends</span> Specification { <span class="directive">public</span> TranslatableString satisfiesTranslatable(<span class="predefined-type">Object</span> obj); <i class="conum" data-value="1"></i><b>(1)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>if returns <code>null</code>, then the constraint is satisfies; otherwise returns the reason why the constraint has not been satisfied.</td> </tr> </table> </div> <div class="paragraph"> <p>Note that if implementing <code>Specification2</code> then there is no need to also provide an implementation of the inherited <code>satisfies(Object)</code> method; this will never be called by the framework for <code>Specification2</code> instances.</p> </div> </div> <div class="sect3"> <h4 id="_adapter_classes">3.8.3. Adapter classes</h4> <div class="paragraph"> <p>The <code>AbstractSpecification</code> and <code>AbstractSpecification2</code> adapter classes provide a partial implementation of the respective interfaces, providing type-safety. (Their design is modelled on the <code>TypesafeMatcher</code> class within <a href="http://hamcrest.org/JavaHamcrest/">Hamcrest</a>).</p> </div> <div class="paragraph"> <p>For example:</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">StartWithCapitalLetterSpecification</span> <span class="directive">extends</span> AbstractSpecification<<span class="predefined-type">String</span>> { <span class="directive">public</span> <span class="predefined-type">String</span> satisfiesSafely(<span class="predefined-type">String</span> proposed) { <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="delimiter">"</span></span>.equals(proposed) ? <span class="string"><span class="delimiter">"</span><span class="content">Empty string</span><span class="delimiter">"</span></span> : !<span class="predefined-type">Character</span>.isUpperCase(proposed.charAt(<span class="integer">0</span>)) ? <span class="string"><span class="delimiter">"</span><span class="content">Does not start with a capital letter</span><span class="delimiter">"</span></span> : <span class="predefined-constant">null</span>; } } <span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> { <span class="annotation">@Property</span>(mustSatisfy=StartWithCapitalLetterSpecification.class) <span class="directive">public</span> <span class="predefined-type">String</span> getFirstName() { ... } ... }</code></pre> </div> </div> <div class="paragraph"> <p>The <code>AbstractSpecification2</code> class is almost identical; its type-safe method is <code>satisfiesTranslatableSafely(T)</code> instead.</p> </div> </div> <div class="sect3"> <h4 id="_combining_specifications">3.8.4. Combining specifications</h4> <div class="paragraph"> <p>There are also adapter classes that can be inherited from to combine specifications:</p> </div> <div class="ulist"> <ul> <li> <p><code>SpecificationAnd</code> - all provided specifications' constraints must be met</p> </li> <li> <p><code>SpecificationOr</code> - at least one provided specifications' constraints must be met</p> </li> <li> <p><code>SpecificationNot</code> - its constraints are met if-and-only-if the provided specification’s constraint was <em>not</em> met.</p> </li> </ul> </div> <div class="paragraph"> <p>Note that these adapter classes inherit <code>Specification</code> but do not inherit <code>Specification2</code>; in other words they do not support i18n.</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_i18n">3.9. i18n support</h3> <div class="paragraph"> <p>The <code>org.apache.isis.applib.services.i18n</code> package contains a single class to support i18n.</p> </div> <div class="sect3"> <h4 id="_rgcms_classes_i18n_TranslatableString">3.9.1. <code>TranslatableString</code></h4> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> TODO - see <a href="ugbtb.html#_ugbtb_i18n">user guide, i18n</a>. </td> </tr> </table> </div> <div class="paragraph"> <p>The <code>TranslatableString</code> utility class …</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_contributee">3.10. Contributee</h3> <div class="paragraph"> <p>The interfaces listed in this chapter act as contributees; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.</p> </div> <div class="sect3"> <h4 id="_rgcms_classes_mixins_HasTransactionId">3.10.1. <code>HasTransactionId</code></h4> <div class="paragraph"> <p>The <code>HasTransactionId</code> interface is a mix-in for any domain objects that reference a transaction id, such as auditing entries or commands, or for <a href="rgsvc.html#_rgsvc_api_InteractionContext"><code>Interaction</code></a>s persisted as published events.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Prior to <code>1.13.0</code>, this identifier was the GUID of the Isis transaction in which the object was created (hence the name). As of <code>1.13.0</code>, this identifier actually is for the request/interaction in which the object was created, so is actually now mis-named.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The interface is defined is:</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">HasTransactionId</span> { <span class="directive">public</span> <span class="predefined-type">UUID</span> getTransactionId(); <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> <span class="type">void</span> setTransactionId(<span class="directive">final</span> <span class="predefined-type">UUID</span> transactionId); }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>unique identifier (a GUID) of this request/interaction.</td> </tr> </table> </div> <div class="paragraph"> <p>Modules that either have domain entity that implement and/or services that contribute this interface are:</p> </div> <div class="ulist"> <ul> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-audit">Isis addons' audit</a> module (<code>AuditEntry</code> entity, <code>AuditingServiceContributions</code> service)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> module (<code>CommandJdo</code> entity, <code>CommandServiceJdoContributions</code> service)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-publishing">Isis addons' publishing</a> module (<code>PublishedEvent</code> entity, <code>PublishingServiceContributions</code>)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module (<code>PublishedEvent</code> entity)</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_mixins_HasUserName">3.10.2. <code>HasUsername</code></h4> <div class="paragraph"> <p>The <code>HasUsername</code> interface is a mix-in for domain objects to be associated with a username. Other services and modules can then contribute actions/collections to render such additional information relating to the activities of the user.</p> </div> <div class="paragraph"> <p>The interface is defined is:</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">HasUsername</span> { <span class="directive">public</span> <span class="predefined-type">String</span> getUsername(); }</code></pre> </div> </div> <div class="paragraph"> <p>Modules that either have domain entity that implement and/or services that contribute this interface are:</p> </div> <div class="ulist"> <ul> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-security">Isis addons' security</a> module ( <code>ApplicationUser</code> entity, <code>HasUsernameContributions</code> service)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-audit">Isis addons' audit</a> module (<code>AuditEntry</code> entity,</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> module’s <code>CommandJdo</code> entity, <code>HasUsernameContributions</code> service)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-publishing">Isis addons' publishing</a> module (<code>PublishedEvent</code> entity)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-sessionlogger">Isis addons' sessionlogger</a> module (<code>SessionLogEntry</code> entity, <code>HasUsernameContributions</code> service)</p> </li> <li> <p>(non-ASF) <a href="http://github.com/isisaddons/isis-module-settings">Isis addons' settings</a> module (<code>UserSettingJdo</code> entity)</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_roles">3.11. Roles</h3> <div class="paragraph"> <p>The interfaces listed in this chapter are role interfaces; they define a contract for the framework to interact with those domain objects that implement these interfaces.</p> </div> <div class="sect3"> <h4 id="_rgcms_classes_roles_HoldsUpdatedAt">3.11.1. <code>HoldsUpdatedAt</code></h4> <div class="paragraph"> <p>The <code>HoldsUpdatedAt</code> role interface allows the (framework-provided) <code>TimestampService</code> to update each object with the current timestamp whenever it is modified in a transaction.</p> </div> <div class="paragraph"> <p>The interface is defined 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">interface</span> <span class="class">HoldsUpdatedAt</span> { <span class="type">void</span> setUpdatedAt(java.sql.Timestamp updatedAt); }</code></pre> </div> </div> <div class="paragraph"> <p>The current time is obtained from the <a href="rgsvc.html#_rgsvc_api_ClockService"><code>ClockService</code></a>.</p> </div> <div class="paragraph"> <p>Entities that implement this interface often also implement <a href="#_rgcms_classes_roles_HoldsUpdatedBy"><code>HoldsUpdatedBy</code></a> role interface; as a convenience the <a href="#_rgcms_classes_roles_Timestampable"><code>Timestampable</code></a> interface combines the two roles.</p> </div> <div class="sect4"> <h5 id="_alternative_approaches">Alternative approaches</h5> <div class="paragraph"> <p>An alternative way to maintain a timestamp is to use JDO’s <code>@Version</code> annotation. With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework’s <code>TimestampService</code>.</p> </div> <div class="paragraph"> <p>For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Version( strategy=VersionStrategy.DATE_TIME, column=<span class="string"><span class="delimiter">"</span><span class="content">version</span><span class="delimiter">"</span></span>) <span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> { ... public java.sql.Timestamp getVersionSequence() { <span class="keyword">return</span> (java.sql.Timestamp) JDOHelper.getVersion(<span class="local-variable">this</span>); } }</code></pre> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_roles_HoldsUpdatedBy">3.11.2. <code>HoldsUpdatedBy</code></h4> <div class="paragraph"> <p>The <code>HoldsUpdatedBy</code> role 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">HoldsUpdatedBy</span> { <span class="type">void</span> setUpdatedBy(<span class="predefined-type">String</span> updatedBy); }</code></pre> </div> </div> <div class="paragraph"> <p>Entities that implement this interface often also implement <a href="#_rgcms_classes_roles_HoldsUpdatedAt"><code>HoldsUpdatedAt</code></a> role interface; as a convenience the <a href="#_rgcms_classes_roles_Timestampable"><code>Timestampable</code></a> interface combines the two roles.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_roles_Timestampable">3.11.3. <code>Timestampable</code></h4> <div class="paragraph"> <p>The <code>Timestampable</code> role interface is a convenience that combines the <a href="#_rgcms_classes_roles_HoldsUpdatedAt"><code>HoldsUpdatedAt</code></a> and <a href="#_rgcms_classes_roles_HoldsUpdatedBy"><code>HoldsUpdatedBy</code></a> interfaces. It is defined 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">interface</span> <span class="class">Timestampable</span> <span class="directive">extends</span> HoldsUpdatedAt, HoldsUpdatedBy { }</code></pre> </div> </div> <div class="paragraph"> <p>The interface no additional methods of its own.</p> </div> <div class="sect4"> <h5 id="_alternatives_4">Alternatives</h5> <div class="paragraph"> <p>An alternative way to maintain a timestamp is to use JDO’s <code>@Version</code> annotation. With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework’s <code>TimestampService</code>. See <a href="#_rgcms_classes_roles_HoldsUpdatedBy"><code>HoldsUpdatedBy</code></a> for further details.</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_mixins">3.12. Mixins</h3> <div class="paragraph"> <p>The interfaces listed in this chapter are role interfaces; they define a contract for the framework to interact with those domain objects that implement these interfaces.</p> </div> <div class="sect3"> <h4 id="_rgcms_classes_mixins_Object">3.12.1. <code>Object</code></h4> <div class="paragraph"> <p>The framework provides a single mixin that contributes to simply <code>java.lang.Object</code>. It provides the ability to download the layout XML for any domain object (in practical terms: entities and view models).</p> </div> <div class="sect4"> <h5 id="_rgcms_classes_mixins_Object_clearHints"><code>clearHints()</code></h5> <div class="paragraph"> <p>When a domain object is rendered the end-user can select different tabs, and for collections can sort the columns, navigate to second pages, or select different views of collections. If the user revisits that object, the <a href="#ugvw.adoc">Wicket viewer</a> will remember these hints and render the domain object in the same state. These rendering hints are also included if the user copies the URL using the anchor link (to right hand of the object’s title).</p> </div> <div class="paragraph"> <p>The <code>Object_clearHints</code> mixin provides the ability for the end-user to discard these hints so that the object is rendered in its initial state:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> clearHints() { ... }</code></pre> </div> </div> <div class="sect5"> <h6 id="_appearance_in_the_ui">Appearance in the UI</h6> <div class="paragraph"> <p>This mixin actions are all associated with the "Metadata" fieldset. If there is no such field set, then the action will be rendered as a top-level action).</p> </div> </div> <div class="sect5"> <h6 id="_related_services">Related Services</h6> <div class="paragraph"> <p>This mixin uses the <a href="rgsvc.html#_rgsvc_spi_HintStore"><code>HintStore</code></a> service to store and retrieve UI hints for each rendered object, per user.</p> </div> </div> </div> <div class="sect4"> <h5 id="_rgcms_classes_mixins_Object_downloadLayoutXml"><code>downloadLayoutXml()</code></h5> <div class="paragraph"> <p>The <code>Object_downloadLayoutXml</code> mixin provides an action to download the <a href="ugfun.html#_ugfun_object-layout_dynamic_xml">layout XML</a> for the current domain object. It has the following signature:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">Object</span> downloadLayoutXml( <span class="annotation">@ParameterLayout</span>(named = <span class="string"><span class="delimiter">"</span><span class="content">File name</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="predefined-type">String</span> fileName, <span class="directive">final</span> LayoutService.Style style) { <i class="conum" data-value="1"></i><b>(1)</b> ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>either current, complete, normalized or minimal.</td> </tr> </table> </div> <div class="paragraph"> <p>See the documentation on <a href="ugfun.html#_ugfun_object-layout_dynamic_xml">layout XML</a> and also the <a href="rgsvc.html#_rgsvc_api_LayoutService"><code>LayoutService</code></a> for more information on these styles</p> </div> <div class="sect5"> <h6 id="_appearance_in_the_ui_2">Appearance in the UI</h6> <div class="paragraph"> <p>This mixin actions are all associated with the "Metadata" fieldset.</p> </div> <div class="paragraph"> <p>A number of other <a href="#_rgcms_classes_mixins_Persistable">mixins</a> also contribute properties and actions to the "Metadata" fieldset.</p> </div> </div> <div class="sect5"> <h6 id="_related_services_2">Related Services</h6> <div class="paragraph"> <p>This mixin calls <a href="rgsvc.html#_rgsvc_api_LayoutService"><code>LayoutService</code></a> to obtain the layout XML.</p> </div> </div> </div> <div class="sect4"> <h5 id="_rgcms_classes_mixins_Object_rebuildMetamodel"><code>rebuildMetamodel()</code></h5> <div class="paragraph"> <p>The <code>Object_rebuildMetamodel</code> mixin provides the ability to discard the current internal metamodel data (an instance of <code>ObjectSpecification</code>) for the domain class of the rendered object, and recreate from code and other sources (most notably, layout XML data). It has the following signature:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> rebuildMetamodel() { ... }</code></pre> </div> </div> <div class="sect5"> <h6 id="_appearance_in_the_ui_3">Appearance in the UI</h6> <div class="paragraph"> <p>This mixin actions are all associated with the "Metadata" fieldset.</p> </div> <div class="paragraph"> <p>A number of other <a href="#_rgcms_classes_mixins_Persistable">mixins</a> also contribute properties and actions to the "Metadata" fieldset.</p> </div> </div> <div class="sect5"> <h6 id="_related_services_3">Related Services</h6> <div class="paragraph"> <p>This mixin calls <a href="rgsvc.html#_rgsvc_api_MetaModelService"><code>MetaModelService</code></a> and the <a href="rgsvc.html#_rgsvc_spi_GridService"><code>GridService</code></a> to invalidate their caches.</p> </div> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_mixins_Dto">3.12.2. <code>Dto</code></h4> <div class="paragraph"> <p>The <code>Dto</code> role interface is intended to be implemented by JAXB-annotated view models, that is, annotated using <a href="rgant.html#_rgant-XmlRootElement"><code>@XmlRootElement</code></a>. It enables the ability to download the XML and XSD schema of those objects using two <a href="ugbtb.html#_ugbtb_decoupling_mixins">mixins</a>, <code>Dto_downloadXml</code> and <code>Dto_downloadXsd</code>.</p> </div> <div class="paragraph"> <p>The interface is just a marker interface (with no members), and is defined 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">interface</span> <span class="class">Dto</span> { }</code></pre> </div> </div> <div class="paragraph"> <p>The <code>Dto_downloadXml</code> mixin defines the following action:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span> <span class="directive">public</span> <span class="type">class</span> <span class="class">Dto_downloadXml</span> { <span class="directive">public</span> Dto_downloadXml(<span class="directive">final</span> Dto dto) { ... } <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> <span class="predefined-type">Object</span> downloadXml(<span class="directive">final</span> <span class="predefined-type">String</span> fileName) { ... } <i class="conum" data-value="2"></i><b>(2)</b> ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>provided as an action to any class that (trivially) implements the <code>Dto</code> interface</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>actually this method is called '$$' in the code, a "special case" that means to use the derive the action name from the class name.</td> </tr> </table> </div> <div class="paragraph"> <p>This will return the XML text wrapped up in a <a href="#_rgcms_classes_value-types_Clob"><code>Clob</code></a>.</p> </div> <div class="paragraph"> <p>The <code>Dto_downloadXsd</code> mixin is similar:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span> <span class="directive">public</span> <span class="type">class</span> <span class="class">Dto_downloadXsd</span> { <span class="directive">public</span> Dto_downloadXsd(<span class="directive">final</span> Dto dto) { ... } <i class="conum" data-value="1"></i><b>(1)</b> <span class="directive">public</span> <span class="predefined-type">Object</span> downloadXsd(<span class="directive">final</span> <span class="predefined-type">String</span> fileName, <span class="directive">final</span> IsisSchemes isisSchemas) { ... } <i class="conum" data-value="2"></i><b>(2)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>provided as an action to any class that (trivially) implements the <code>Dto</code> interface</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.</td> </tr> </table> </div> <div class="paragraph"> <p>If the domain object’s JAXB annotations reference only a single XSD schema then this will return that XML text as a <a href="#_rgcms_classes_value-types_Clob"><code>Clob</code></a> of that XSD. If there are multiple XSD schemas referenced then the action will return a zip of those schemas, wrapped up in a <a href="#_rgcms_classes_value-types_Blob"><code>Blob</code></a>. The <code>IsisSchemas</code> parameter to the action can be used to optionally ignore the common <a href="#_rgcms_schema">Apache Isis schemas</a> (useful if there is only one other XSD schema referenced by the DTO).</p> </div> <div class="sect4"> <h5 id="_related_services_4">Related Services</h5> <div class="paragraph"> <p>The <code>Dto_downloadXml</code> and <code>Dto_downloadXsd</code> delegate to the <a href="rgsvc.html#_rgsvc_api_JaxbService"><code>JaxbService</code></a> to actually generate the XML/XSD.</p> </div> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_mixins_Persistable">3.12.3. <code>Persistable</code></h4> <div class="paragraph"> <p>All domain entities automatically implement the DataNucleus <code>Persistable</code> role interface as a result of the enhancer process (the fully qualified class name is <code>org.datanucleus.enhancement.Persistable</code>). So as a developer you do not need to write any code to obtain the mixins that contribute to this interface.</p> </div> <div class="sect4"> <h5 id="_rgcms_classes_mixins_Persistable_downloadJdoMetadata"><code>downloadJdoMetadata()</code></h5> <div class="paragraph"> <p>The <code>Persistable_downloadJdoMetadata</code> mixin provides an action which allows the JDO <a href="http://www.datanucleus.org/products/datanucleus/jdo/metadata_xml.html">class metadata</a> to be downloaded as XML. It has the following signature:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">Clob</span> downloadJdoMetadata( <i class="conum" data-value="1"></i><b>(1)</b> <span class="annotation">@ParameterLayout</span>(named = <span class="string"><span class="delimiter">"</span><span class="content">.jdo file name</span><span class="delimiter">"</span></span>) <span class="directive">final</span> <span class="predefined-type">String</span> fileName) { ... }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>returns the XML text wrapped up in a <a href="#_rgcms_classes_value-types_Clob"><code>Clob</code></a>.</td> </tr> </table> </div> <div class="sect5"> <h6 id="_appearance_in_the_ui_4">Appearance in the UI</h6> <div class="paragraph"> <p>This mixin action is associated with the "Metadata" fieldset, and will appear as a panel drop-down action.</p> </div> <div class="paragraph"> <p>These mixin properties are all associated with the "Metadata" fieldset. The <a href="#_rgcms_classes_mixins_Object">Object mixin</a> also contribute an action to the "Metadata" fieldset.</p> </div> </div> <div class="sect5"> <h6 id="_related_services_5">Related Services</h6> <div class="paragraph"> <p>The mixin delegates to the <a href="rgsvc.html#_rgsvc_api_IsisJdoSupport"><code>IsisJdoSupport</code></a> service to obtain a reference to the JDO <code>PersistenceManagerFactory</code>.</p> </div> </div> </div> <div class="sect4"> <h5 id="_rgcms_classes_mixins_Persistable_datanucleusXxx"><code>datanucleusXxx</code></h5> <div class="paragraph"> <p>The framework provides a number of mixins that expose the datanucleus Id and version of a persistable domain entity. Several implementations are provided to support different datatypes:</p> </div> <div class="ulist"> <ul> <li> <p><code>Persistable_datanucleusIdLong</code> will expose the entity’s id, assuming that the id is or can be cast to <code>java.lang.Long</code>. Otherwise the property will be hidden.</p> </li> <li> <p><code>Persistable_datanucleusVersionTimestamp</code> will expose the entity’s version, assuming that the version is or can be cast to <code>java.sql.Timestamp</code>. Otherwise the property will be hidden.</p> </li> <li> <p><code>Persistable_datanucleusVersionLong</code> will expose the entity’s version, assuming that the version is or can be cast to <code>java.lang.Long</code>. Otherwise the property will be hidden.</p> </li> </ul> </div> <div class="sect5"> <h6 id="_appearance_in_the_ui_5">Appearance in the UI</h6> <div class="paragraph"> <p>These mixin properties are all associated with the "Metadata" fieldset. The <a href="#_rgcms_classes_mixins_Object">Object mixin</a> also contribute an action to the "Metadata" fieldset.</p> </div> </div> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_classes_layout">3.13. Layout</h3> <div class="paragraph"> <p>The <code>org.apache.isis.applib.layout</code> package defines a number of classes that allow the layout of domain objects (entities and view models) to be customized. These classes fall into two main categories:</p> </div> <div class="ulist"> <ul> <li> <p>grid classes, that define a grid structure of rows, columns, tab groups and tabs, and;</p> </li> <li> <p>common component classes, that capture the layout metadata for an object’s properties, collections and actions. These are bound (or associated) to the regions of the grid</p> </li> </ul> </div> <div class="paragraph"> <p>The framework provides an implementation of the grid classes modelled closely on <a href="http://getbootstrap.com">Bootstrap 3</a>, along with <a href="#ugvw.adoc">Wicket viewer</a> components capable of rendering that grid system. In principle it is also possible to extend the layout architecture for other grid systems. The component classes, though, are intended to be reusable across all grid systems.</p> </div> <div class="paragraph"> <p>The component classes, meanwhile, are broadly equivalent to the "layout" annotations (<a href="rgant.html#_rgant-PropertyLayout"><code>@PropertyLayout</code></a>, <a href="rgant.html#_rgant-CollectionLayout"><code>@CollectionLayout</code></a>, <a href="rgant.html#_rgant-ActionLayout"><code>@ActionLayout</code></a> and <a href="rgant.html#_rgant-DomainObjectLayout"><code>@DomainObjectLayout</code></a></p> </div> <div class="paragraph"> <p>All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (the <code>component</code> classes in the <code><a href="http://isis.apache.org/applib/layout/component" class="bare">http://isis.apache.org/applib/layout/component</a></code> XSD namespace, the bootstrap 3 grid classes in the <code><a href="http://isis.apache.org/applib/layout/grid/bootstrap3" class="bare">http://isis.apache.org/applib/layout/grid/bootstrap3</a></code> XSD namespace). This ability to serialize to/from XML is used by the <a href="rgsvc.html#_rgsvc_spi_GridLoaderService"><code>GridLoaderService</code></a>, the default implementation of which reads the grid layout for a domain class from a <code>.layout.xml</code> file on the classpath.</p> </div> <div class="sect3"> <h4 id="_rgcms_classes_layout_component">3.13.1. Component</h4> <div class="paragraph"> <p>The component classes reside in the <code>org.apache.isis.applib.layout.component</code> package, and consist of:</p> </div> <div class="ulist"> <ul> <li> <p><code>FieldSet</code><br></p> <div class="paragraph"> <p>A fieldset (previously also called a property group or member group) of a number of the domain object’s properties (along with any associationed actions of those properties).</p> </div> </li> <li> <p>layout data classes, which correspond to the similarly named annotations:</p> <div class="ulist"> <ul> <li> <p><code>PropertyLayoutData</code>, corresponding to the <a href="rgant.html#_rgant-PropertyLayout"><code>@PropertyLayout</code></a> annotation;</p> </li> <li> <p><code>CollectionLayoutData</code>, corresponding to the <a href="rgant.html#_rgant-CollectionLayout"><code>@CollectionLayout</code></a> annotation;</p> </li> <li> <p><code>ActionLayoutData</code>, corresponding to the <a href="rgant.html#_rgant-ActionLayout"><code>@ActionLayout</code></a> annotation;</p> </li> <li> <p><code>DomainObjectLayoutData</code>, corresponding to the <a href="rgant.html#_rgant-DomainObjectLayout"><code>@DomainObjectLayout</code></a> annotation.</p> </li> </ul> </div> </li> </ul> </div> <div class="paragraph"> <p>In addition, the component package includes <code>Grid</code>, representing the top level container for a custom layout for a domain object. <code>Grid</code> itself is merely an interface, but it also defines the visitor pattern to make it easy for validate and normalize the grid layouts. The <code>GridAbstract</code> convenience superclass provides a partial implementation of this visitor pattern.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_classes_layout_grid-bootstrap3">3.13.2. Bootstrap3 Grid</h4> <div class="paragraph"> <p>As noted above, the default bootstrap3 grid classes are modelled closely on <a href="http://getbootstrap.com">Bootstrap 3</a>. Bootstrap’s <a href="http://getbootstrap.com/css/#grid">grid system</a> divides the page width equally into 12 columns, and so each column spans 1 or more of these widths. Thus, a column with a span of 12 is the full width, one with a span of 6 is half the width, one with a span of 4 is a third of the width, and so on.</p> </div> <div class="paragraph"> <p>When specifying the span of a column, Bootstrap also allows a size to be specified (<code>XS</code>, <code>SM</code>, <code>MD</code>, <code>LG</code>). The size determines the rules for responsive design. Apache Isis defaults to <code>MD</code> but this can be overridden. It is also possible to specify multiple size/spans for a given column.</p> </div> <div class="paragraph"> <p>The grid classes provided by Apache Isis reside in the <code>org.apache.isis.applib.layout.grid.bootstrap3</code> package, and consist of:</p> </div> <div class="ulist"> <ul> <li> <p><code>BS3Grid</code><br></p> <div class="paragraph"> <p>Consists of a number of <code>BS3Row</code>s. <br></p> </div> <div class="paragraph"> <p>This class is the concrete implementation of <code>Grid</code> interface, discussed previously. As such, it extends the <code>Grid.Visitor</code> to iterate over all of the <code>Row</code>s of the grid.</p> </div> </li> <li> <p><code>BS3Row</code><br></p> <div class="paragraph"> <p>A container of <code>BS3Col</code>s. This element is rendered as <code><div class="row"></code>.</p> </div> </li> <li> <p><code>BS3Col</code><br></p> <div class="paragraph"> <p>A container of almost everything else. A column most commonly contains properties (grouped into <code>FieldSet</code>s, described above) or collections (specified by <code>CollectionLayoutData</code>, also above). However, a <code>Col</code> might instead contain a <code>BS3TabGroup</code> (described below) in order that the object members is arranged into tabs. <br></p> </div> <div class="paragraph"> <p>It is also possible for a <code>Col</code> to contain the object’s title/icon (using <code>DomainObjectLayoutData</code>) or indeed arbitrary actions (using <code>`ActionLayoutData</code>).<br></p> </div> <div class="paragraph"> <p>Finally, a <code>BS3Col</code> can also contain other <code>BS3Row</code>s, allowing arbitrarily deep hierarchies of containers as required.</p> </div> <div class="paragraph"> <p>This element is rendered as, for example, <code><div class="col-md-4"></code> (for a size <code>MD</code>, span of 4).</p> </div> </li> <li> <p><code>BS3TabGroup</code><br></p> <div class="paragraph"> <p>A container of <code>BS3Tab</code>s.</p> </div> </li> <li> <p><code>BS3Tab</code><br></p> <div class="paragraph"> <p>A container of <code>BS3Row</code>s, which will in turn contain <code>BS3Col</code>s and thence ultimately the object’s members.</p> </div> </li> </ul> </div> <div class="paragraph"> <p>There are also two close cousins of <code>Col</code>, namely <code>ClearFixVisible</code> and <code>ClearFixHidden</code>. These map to Bootstrap’s <a href="http://getbootstrap.com/css/#responsive-utilities">responsive utility class</a>es, and provide greater control for responsive designs.</p> </div> <div class="paragraph"> <p>As you can probably guess, the <code>BS3Grid</code> is the top-level object (that is, it is JAXB <code>@XmlRootElement</code>); this is the object that is serialized to/from XML.</p> </div> <div class="paragraph"> <p>All of these classes also allow custom CSS to be specified; these are added to the CSS classes for the corresponding <code><div</code>> in the rendered page. The <a href="ugvw.html#_ugvw_customisation_tweaking-css-classes"><code>application.css</code></a> file can then be used for application-specific CSS, allowing arbitrary fine-tuning of the layout of the page.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_rgcms_schema">4. Schema</h2> <div class="sectionbody"> <div class="paragraph"> <p>Most applications need to integrate with other apps in the enterprise. To facilitate such integration scenarios, Apache Isis defines a number of standard XSD schemas:</p> </div> <div class="ulist"> <ul> <li> <p>the <a href="#_rgcms_schema-cmd">command</a> schema, which captures the <em>intention</em> of a user to invoke an action or edit a property</p> </li> <li> <p>the <a href="#_rgcms_schema-ixn">interaction execution</a> schema, which captures the actual execution of an action invocation/property edit</p> </li> <li> <p>the <a href="#_rgcms_schema-chg">changes</a> schema, which captures which objects have been created, updated or deleted as the result of an execution of an action invocation/property edit</p> </li> <li> <p>the <a href="#_rgcms_schema-aim">action memento invocation</a> schema (deprecated in <code>1.13.0</code>, replaced by either "cmd" or "ixn"), which allows action invocations to be captured and reified.</p> </li> </ul> </div> <div class="paragraph"> <p>These each use XSD types defined by the <a href="#_rgcms_schema-common">common schema</a> (most notably the <code>oidDto</code> complex type which identifies a domain object).</p> </div> <div class="paragraph"> <p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> and <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> modules uses these schemas to reify corresponding applib objects (<code>Command</code>, <code>Interaction.Execution</code> and <code>PublishedObjects</code>), either to persist or publishing using an <a href="http://activemq.apache.org">Apache ActiveMQ</a> message queue.</p> </div> <div class="paragraph"> <p>The sections below discuss these schemas in more detail.</p> </div> <div class="sect2"> <h3 id="_rgcms_schema-cmd">4.1. Command</h3> <div class="paragraph"> <p>The command ("cmd") schema defines the serialized form of the <em>intention</em> to invoke an action or to edit a property.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Mixin actions are represented as regular actions on the mixed-in object. In other words, the fact that the actual implementation of the action is defined by a mixin is an implementation detail only.</p> </div> </td> </tr> </table> </div> <div class="sect3"> <h4 id="_rgcms_schema-cmd_commandDto">4.1.1. <code>commandDto</code></h4> <div class="paragraph"> <p>The <code>commandDto</code> root element is defined as:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/cmd</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="attribute-name">elementFormDefault</span>=<span class="string"><span class="delimiter">"</span><span class="content">qualified</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:xs</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/cmd</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:com</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:import</span> <span class="attribute-name">namespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="attribute-name">schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">../common/common-1.0.xsd</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">commandDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">majorVersion</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">minorVersion</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">transactionId</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">user</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="6"></i><b>(6)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">targets</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:oidsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="7"></i><b>(7)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">member</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="8"></i><b>(8)</b> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> ... <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the command schema has a namespace URI of "http://isis.apache.org/schema/cmd". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>uses complex types defined in the <a href="#_rgcms_schema_common">"common" schema</a>.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>definition of the <code>commandDto</code> root element. The corresponding XML will use this as its top-level element.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>unique identifier for the transaction in which this command is created. The transaction Id is used to correlate to the <a href="#_rgcms_schema_interaction">interaction</a> that executes the command, and to any <a href="#_rgcms_schema_changes">changes</a> to domain objects occurring as a side-effect of that interaction.</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>the name of the user who created the command (whose intention it is to invoke the action/edit the property).</td> </tr> <tr> <td><i class="conum" data-value="7"></i><b>7</b></td> <td>the target object (or objects) to be invoked. As of <code>1.13.0</code>, a bulk action will create multiple commands, each with only a single target, but a future version of the framework may also support a single bulk command against this multiple targets (ie all-or-nothing).</td> </tr> <tr> <td><i class="conum" data-value="8"></i><b>8</b></td> <td>the <code>memberDto</code>, defined below, the captures the action/property and arguments/new value.</td> </tr> </table> </div> <div class="paragraph"> <p>The <code>CommandDto</code> DTO corresponding to the <code>commandDto</code> root element can be marshalled to/from XML using the <code>CommandDtoUtils</code> class.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_schema-cmd_memberDto">4.1.2. <code>memberDto</code> and subtypes</h4> <div class="paragraph"> <p>The <code>memberDto</code> complex type is an abstract type representing the intention to either invoke an action or to edit a property. The <code>actionDto</code> and <code>propertyDto</code> are the concrete subtypes:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/cmd</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span><span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberDto</span><span class="delimiter">"</span></span> <span class="attribute-name">abstract</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberIdentifier</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">interactionType</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:interactionType</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">actionDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:complexContent></span> <span class="tag"><xs:extension</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">parameters</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">paramsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:extension></span> <span class="tag"></xs:complexContent></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">propertyDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:complexContent></span> <span class="tag"><xs:extension</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">newValue</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:valueWithTypeDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:extension></span> <span class="tag"></xs:complexContent></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the <code>memberDto</code> is an abstract type. Its primary responsibility is simply to identify the member (action or property).</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the <code>interactionType</code> attribute indicates whether the member is an action or a property.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the <code>actionDto</code> complex type captures the set of parameters (also including the argument values) with which to invoke the action. The <code>paramsDto</code> type is defined <a href="#_rgcms_schema-cmd_ancillary">below</a>.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the <code>propertyDto</code> complex type captures the new value (possibly <code>null</code>) to set the property to.</td> </tr> </table> </div> <div class="paragraph"> <p>Note also that there is a corresponding <a href="#_rgcms_schema-ixn_memberExecutionDto"><code>memberExecutionDto</code></a> complex type in the "ixn" schema that is for the actual execution (capturing metrics about its execution and also the return value if an action invocation).</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_schema-cmd_ancillary">4.1.3. Ancillary types</h4> <div class="paragraph"> <p>The schema also defines a small number of supporting types:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/cmd</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span><span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">paramsDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:sequence</span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">unbounded</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">parameter</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">paramDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">paramDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:complexContent></span> <span class="tag"><xs:extension</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:valueWithTypeDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">name</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">required</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:extension></span> <span class="tag"></xs:complexContent></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the <code>paramsDto</code> is simply the list of parameter/arguments.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the <code>paramDto</code> complex type essentially combines a parameter with its corresponding argument: a named value that has a type. It extends the <code>valueWithTypeDto</code> complex type taken from the <a href="#_rgcms_schema-common">"common"</a> schema.</td> </tr> </table> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_schema-ixn">4.2. Interaction Execution</h3> <div class="paragraph"> <p>The interaction ("ixn") schema defines the serialized form of an action invocation or a property edit. In fact, it actually defines a call-graph of such executions for those cases where the <a href="rgsvc.html#_rgsvc_api_WrapperFactory"><code>WrapperFactory</code></a> is used to execute sub-actions/property edits.</p> </div> <div class="paragraph"> <p>Each execution identifies the target object, the member to invoke, and the arguments. It also captures metrics about the execution, and the result of the execution (eg return value of an action invocation).</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Mixin actions are represented as regular actions on the mixed-in object. In other words, the fact that the actual implementation of the action is defined by a mixin is an implementation detail only.</p> </div> </td> </tr> </table> </div> <div class="sect3"> <h4 id="_rgcms_schema-ixn_interactionDto">4.2.1. <code>interactionDto</code></h4> <div class="paragraph"> <p>The <code>interactionDto</code> root element is defined as:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/ixn</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="attribute-name">elementFormDefault</span>=<span class="string"><span class="delimiter">"</span><span class="content">qualified</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:xs</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/ixn</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:cmd</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/cmd</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:com</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:import</span> <span class="attribute-name">namespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="attribute-name">schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">../common/common-1.0.xsd</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:import</span> <span class="attribute-name">namespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/cmd</span><span class="delimiter">"</span></span> <span class="attribute-name">schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">../cmd/cmd-1.0.xsd</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">interactionDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">majorVersion</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">minorVersion</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">transactionId</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">execution</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberExecutionDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="6"></i><b>(6)</b> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the interaction schema has a namespace URI of "http://isis.apache.org/schema/ixn". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>uses complex types defined in the <a href="#_rgcms_schema_common">"common" schema</a> and also the <a href="#_rgcms_schema_cmd">"cmd" schema</a></td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>definition of the <code>interactionDto</code> root element. The corresponding XML will use this as its top-level element.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>unique identifier for the transaction in which this interaction is being executed. The transaction Id is used to correlate back to the <a href="#_rgcms_schema_command">command</a> that represented the intention to perform this execution, as well as to any <a href="#_rgcms_schema_changes">changes</a> to domain objects that occur as a side-effect of the interaction.</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>the top-level <code>memberExecutionDto</code>, defined below, either an action invocation or edit of a property.</td> </tr> </table> </div> <div class="paragraph"> <p>The <code>InteractionDto</code> DTO corresponding to the <code>interactionDto</code> root element can be marshalled to/from XML using the <code>InteractionDtoUtils</code> class.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_schema-ixn_memberExecutionDto">4.2.2. <code>memberExecutionDto</code></h4> <div class="paragraph"> <p>The <code>memberExecutionDto</code> complex type is an abstract type representing either the invocation an action or the editing of a property. It corresponds to the <a href="#_rgcms_schema-cmd_memberDto"><code>memberDto</code></a> of the "cmd" schema; some elements are copied directly:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/ixn</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span> <span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberExecutionDto</span><span class="delimiter">"</span></span> <span class="attribute-name">abstract</span>=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">sequence</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">target</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:oidDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberIdentifier</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">user</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">title</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="6"></i><b>(6)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">metrics</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">metricsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="7"></i><b>(7)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">threw</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">exceptionDto</span><span class="delimiter">"</span></span> <i class="conum" data-value="8"></i><b>(8)</b> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">childExecutions</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="9"></i><b>(9)</b> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">execution</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberExecutionDto</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">unbounded</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> <span class="tag"></xs:sequence></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">interactionType</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:interactionType</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="10"></i><b>(10)</b> <span class="tag"></xs:complexType></span> ... <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the <code>memberExecutionDto</code> is an abstract type</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>uniquely identifies this execution within the transaction. Can be combined with <code>transactionId</code> to create a unique identifier (across all other interaction executions and also changed objects events) of this particular interaction execution.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the target object, corresponding to one of the elements of the <code>targets</code> element of the <a href="#_rgcms_schema-cmd_memberDto"><code>memberDto</code></a></td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the member identifier; corresponds to <code>memberIdentifier</code> of the <code>member</code> element of the <a href="#_rgcms_schema-cmd_memberDto"><code>memberDto</code></a></td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>the user executing the action invocation/property edit; corresponds to the <code>user</code> element of the <a href="#_rgcms_schema-cmd_memberDto"><code>memberDto</code></a></td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>the current "human-friendly" title of the target object</td> </tr> <tr> <td><i class="conum" data-value="7"></i><b>7</b></td> <td>the set of metrics captured for this execution, of type <code>metricsDto</code> defined <a href="#_rgcms_schema-ixn_ancillary">below</a>.</td> </tr> <tr> <td><i class="conum" data-value="8"></i><b>8</b></td> <td>if the action invocation/property edit threw an exception, then this is captured here.</td> </tr> <tr> <td><i class="conum" data-value="9"></i><b>9</b></td> <td>if any sub-actions or sub-edits were performed via the <a href="rgsvc.html#_rgsvc_api_WrapperFactory"><code>WrapperFactory</code></a>, then these are captured in the <code>childExecutions</code> element.</td> </tr> <tr> <td><i class="conum" data-value="10"></i><b>10</b></td> <td>the <code>interactionType</code> attribute indicates whether the member is an action or a property (similar attribute exists for the "cmd" schema).</td> </tr> </table> </div> <div class="paragraph"> <p>The <code>actionInvocationDto</code> and <code>propertyEditDto</code> are the concrete subtypes:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/ixn</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span> <span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">actionInvocationDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:complexContent></span> <span class="tag"><xs:extension</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberExecutionDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">parameters</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">cmd:paramsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">returned</span><span class="delimiter">"</span></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:valueWithTypeDto</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:extension></span> <span class="tag"></xs:complexContent></span> <span class="tag"></xs:complexType></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">propertyEditDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:complexContent></span> <span class="tag"><xs:extension</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">memberExecutionDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">newValue</span><span class="delimiter">"</span></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:valueWithTypeDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:extension></span> <span class="tag"></xs:complexContent></span> <span class="tag"></xs:complexType></span> ... <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the <code>actionInvocationDto</code> inherits from <code>memberExecutionDto</code>. It corresponds to the similar <a href="#_rgcms_schema-cmd_memberDto"><code>actionDto</code></a> complex type of the "cmd" schema</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the <code>parameters</code> element captures the parameter and argument values; for the top-level execution it is a direct copy of the corresponding <code>parameters</code> element of the <code>actionDto</code> complex type of the "cmd" schema.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the <code>returned</code> element captures the returned value (if not void). It is not valid for both this element and the inherited <code>threw</code> element to both be populated.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the <code>propertyEditDto</code> inherits from <code>memberExecutionDto</code>. It corresponds to the similar <a href="#_rgcms_schema-cmd_memberDto"><code>propertyDto</code></a> complex type of the "cmd" schema</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>the <code>newValue</code> element captures the new value; for the top-level execution it is a direct copy of the corresponding <code>newValue</code> element of the <code>propertyDto</code> complex type of the "cmd" schema.</td> </tr> </table> </div> </div> <div class="sect3"> <h4 id="_rgcms_schema-ixn_ancillary">4.2.3. Ancillary types</h4> <div class="paragraph"> <p>The schema also defines a small number of supporting types:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/ixn</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span> <span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">metricsDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">timings</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:periodDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">objectCounts</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">objectCountsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">objectCountsDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">loaded</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:differenceDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">dirtied</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:differenceDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">exceptionDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">message</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">stackTrace</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">causedBy</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">exceptionDto</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the <code>metricsDto</code> captures the time to perform an execution, and also the differences in various object counts.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the <code>objectCountsDto</code> complex type is the set of before/after differences, one for each execution; the framework tracks number of objects loaded (read from) the database and the number of objects dirtied (will need to be saved back to the database). Together these metrics give an idea of the "size" of this particular execution.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the <code>exceptionDto</code> complex type defines a structure for capturing the stack trace of any exception that might occur in the course of invoking an action or editing a property.</td> </tr> </table> </div> <div class="paragraph"> <p>The <a href="#_rgcms_schema_changes">changes</a> schema also provides metrics on the number of objects loaded/changed, but relates to the entire interaction rather than just one (sub)execution of an interaction.</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_schema-chg">4.3. Changes</h3> <div class="paragraph"> <p>The changes ("chg") schema defines the serialized form identifying which objects have been created, updated or deleted as the result of invoking an action or editing a property. It also captures a number of other metrics counts (number of objects loaded, number of object properties modified), useful for profiling.</p> </div> <div class="paragraph"> <p>An instance of the DTO (corresponding to this schema) is used within the <a href="rgsvc.html#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> SPI, identifying changed objects that are to be published (as per <a href="rgant.html#_rgant_DomainObject_publishing"><code>@DomainObject#publishing()</code></a> or equivalent).</p> </div> <div class="sect3"> <h4 id="__code_changesdto_code">4.3.1. <code>changesDto</code></h4> <div class="paragraph"> <p>The <code>changesDto</code> root element is defined as:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/chg</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="attribute-name">elementFormDefault</span>=<span class="string"><span class="delimiter">"</span><span class="content">qualified</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:xs</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/chg</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:com</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:import</span> <span class="attribute-name">namespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="attribute-name">schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">../common/common-1.0.xsd</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">changesDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">majorVersion</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">minorVersion</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">default</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">transactionId</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">sequence</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="6"></i><b>(6)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">completedAt</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:dateTime</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="7"></i><b>(7)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">user</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="8"></i><b>(8)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">objects</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">objectsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="9"></i><b>(9)</b> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> ... <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the changes schema has a namespace URI of "http://isis.apache.org/schema/chg". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>uses complex types defined in the <a href="#_rgcms_schema_common">"common" schema</a>.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>definition of the <code>changesDto</code> root element. The corresponding XML will use this as its top-level element.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>unique identifier for the transaction in which this interaction is being executed. The transaction Id is used to correlate back to the <a href="#_rgcms_schema_command">command</a> that represented the intention to perform this execution, as well as to the <a href="#_rgcms_schema_interaction">interaction</a> that executes said command.</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>uniquely identifies this set of changes within the interaction. Can be combined with <code>transactionId</code> to create a unique identifier (across all other changed object events and also any interaction executions) of this particular set of changed objects.</td> </tr> <tr> <td><i class="conum" data-value="7"></i><b>7</b></td> <td>the date/time that the transaction that dirtied this objects completed</td> </tr> <tr> <td><i class="conum" data-value="8"></i><b>8</b></td> <td>the user that executed the (top-level) action invocation/property edit.</td> </tr> <tr> <td><i class="conum" data-value="9"></i><b>9</b></td> <td>identifies the objects that have changed.</td> </tr> </table> </div> <div class="paragraph"> <p>The <code>ChangesDto</code> DTO corresponding to the <code>changesDto</code> root element can be marshalled to/from XML using the <code>ChangesDtoUtils</code> class.</p> </div> </div> <div class="sect3"> <h4 id="__code_objectsdto_code">4.3.2. <code>objectsDto</code></h4> <div class="paragraph"> <p>The <code>objectsDto</code> complex type actually identifies the objects created, updated or deleted. It also captures additional metrics counters:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/chg</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span> <span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">objectsDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">loaded</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">created</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:oidsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">updated</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:oidsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">deleted</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">com:oidsDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">propertiesModified</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the number of objects that were loaded, in total, by the interaction.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the identities of the objects that were, respectively, created, updated or deleted within the transaction.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the number of objects' properties changed, in total, by the interaction.</td> </tr> </table> </div> <div class="paragraph"> <p>The <a href="#_rgcms_schema_ixn">interaction</a> schema also provides metrics on the number of objects loaded/changed, but is more granular, each figure relating to a single (sub-)execution within an interaction.</p> </div> </div> </div> <div class="sect2"> <h3 id="_rgcms_schema-aim">4.4. Action Invocation Memento</h3> <div class="paragraph"> <p>The "aim" schema defines the serialized form (or memento) of an action invocation.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>This schema has been removed in <code>1.13.0</code>, replaced with <a href="#_rgcms_schema-ixn">ixn.xsd</a> (for action invocations/property edits) and with <a href="#_rgcms_schema-cmd">cmd.xsd</a> (commands, ie the <em>intention</em> to invoke an action/edit a property).</p> </div> <div class="paragraph"> <p>The remaining content on this page describes how <code>CommandContext</code> works up to v1.12.x. However, as of <code>1.13.0</code> the <code>CommandContext</code> uses its own <code>cmd.xsd</code> schema).</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action "through" the UI, by way of the <a href="rgsvc.html#_rgsvc_api_CommandContext">CommandContext</a> service. Using the <code>ActionInvocationMementoDtoUtils</code> utility class, a service can instantiate <code>ActionInvocationMementoDto</code> which can then be serialized to/from using the same <code>ActionInvocationMementoDtoUtils</code> class.</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"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/aim</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="attribute-name">elementFormDefault</span>=<span class="string"><span class="delimiter">"</span><span class="content">qualified</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:xs</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/aim</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:common</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:import</span> <span class="attribute-name">namespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="attribute-name">schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common/common-1.0.xsd</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">actionInvocationMementoDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">metadata</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">transactionId</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">sequence</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">timestamp</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:dateTime</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="6"></i><b>(6)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">target</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">common:oidDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="7"></i><b>(7)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">targetClass</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="8"></i><b>(8)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">targetAction</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="9"></i><b>(9)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">actionIdentifier</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="10"></i><b>(10)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">user</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="11"></i><b>(11)</b> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">title</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="12"></i><b>(12)</b> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">payload</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">parameters</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="13"></i><b>(13)</b> <span class="tag"><xs:complexType></span> <span class="tag"><xs:sequence</span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">unbounded</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">param</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">paramDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">num</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">required</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">return</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">common:valueDto</span><span class="delimiter">"</span></span> <i class="conum" data-value="14"></i><b>(14)</b> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:element></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">paramDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="15"></i><b>(15)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">value</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">common:valueDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="16"></i><b>(16)</b> <span class="tag"></xs:sequence></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">parameterName</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">required</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="17"></i><b>(17)</b> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">parameterType</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">required</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">common:valueType</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">null</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">optional</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:boolean</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:complexType></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the aim schema has a namespace URI of "http://isis.apache.org/schema/aim". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>reuses the <a href="#_rgcms_schema-common">common</a> schema</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>definition of the <code>actionInvocationMementoDto</code> complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the unique transaction Id (a guid) allocated by the framework for each and every transaction</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>a sequence number within the transaction. It is possible for there to be more than one action invocation to be</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>when the action was invoked</td> </tr> <tr> <td><i class="conum" data-value="7"></i><b>7</b></td> <td>target object, as an OID (using <code>oidDto</code> from the <a href="#_rgcms_schema-common">common</a> schema)</td> </tr> <tr> <td><i class="conum" data-value="8"></i><b>8</b></td> <td>fully qualified class name of the target object, for information only</td> </tr> <tr> <td><i class="conum" data-value="9"></i><b>9</b></td> <td>name of the action, for information only</td> </tr> <tr> <td><i class="conum" data-value="10"></i><b>10</b></td> <td>Javadoc style unique identifier for the action.</td> </tr> <tr> <td><i class="conum" data-value="11"></i><b>11</b></td> <td>User that invoked the action</td> </tr> <tr> <td><i class="conum" data-value="12"></i><b>12</b></td> <td>title of the target object, for information only</td> </tr> <tr> <td><i class="conum" data-value="13"></i><b>13</b></td> <td>Collection of parameter/arguments, defined in terms of the <code>paramDto</code> complex type (discussed just below)</td> </tr> <tr> <td><i class="conum" data-value="14"></i><b>14</b></td> <td>The return value of the action, if known (and not void)</td> </tr> <tr> <td><i class="conum" data-value="15"></i><b>15</b></td> <td>The <code>paramDto</code> defines both an action parameter and its corresponding argument values</td> </tr> <tr> <td><i class="conum" data-value="16"></i><b>16</b></td> <td>The value of the parameter, in other words an argument value</td> </tr> <tr> <td><i class="conum" data-value="17"></i><b>17</b></td> <td>Metadata about the parameter itself: its name, type, optionality.</td> </tr> </table> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>As of <code>1.11.0</code> through <code>1.12.2</code> this schema is not used directly by the framework; in particular <code>Command#setMemento(…)</code> sets a similar but less formal XML structure. This may change in the future.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_rgcms_schema-common">4.5. Common Schema</h3> <div class="paragraph"> <p>The "common" schema defines a number of complex types that are used by other higher-level schemas.</p> </div> <div class="sect3"> <h4 id="_rgcms_schema-common_oidDto">4.5.1. <code>oidDto</code></h4> <div class="paragraph"> <p>The <code>oidDto</code> complex type captures an object’s type and its identifier. This is basically a formal XML equivalent to the <code>Bookmark</code> object obtained from the <a href="rgsvc.html#_rgsvc_api_BookmarkService"><code>BookmarkService</code></a>.</p> </div> <div class="paragraph"> <p>Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by a given Apache Isis application. With it, we have the ability to lookup any arbitrary object. Further discussion and examples can be found <a href="ugfun.html#_ugfun_core-concepts_building-blocks_oid">here</a>.</p> </div> <div class="paragraph"> <p>The <code>oidDto</code> complex type is defined as:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="attribute-name">elementFormDefault</span>=<span class="string"><span class="delimiter">"</span><span class="content">qualified</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <span class="attribute-name">xmlns:xs</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">oidDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:sequence</span><span class="tag">/></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">id</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">objectState</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">bookmarkObjectState</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:simpleType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">bookmarkObjectState</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="5"></i><b>(5)</b> <span class="tag"><xs:restriction</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">persistent</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">transient</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">viewModel</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:restriction></span> <span class="tag"></xs:simpleType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">oidsDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="6"></i><b>(6)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">oid</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">oidDto</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">unbounded</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> ... <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>the common schema has a namespace URI of "http://isis.apache.org/schema/common". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>the <code>oidDto</code> complex type defines the unique identifier for any domain object: its type, and an identifier. The <code>objectState</code> attribute can usually be omitted (indicating a persistent object)</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>the object type, corresponding to either the <a href="rgant.html#_rgant-DomainObject_objectType"><code>@DomainObject#objectType()</code></a> attribute, or to the (JDO) <a href="rgant.html#_rgant-PersistenceCapable"><code>@PersistenceCapable</code></a> annotation (<code>schema</code> and/or <code>table</code> attributes), or to the (JDO) <a href="rgant.html#_rgant-Discriminator"><code>@Discriminator</code></a> annotation. If none is specified, then the fully qualified class name will be used.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>the object identifier (aka primary key), converted to string form.</td> </tr> <tr> <td><i class="conum" data-value="5"></i><b>5</b></td> <td>the <code>bookmarkObjectState</code> enumerates the possible persistence states of the referenced object. In previous versions of the schema the attribute was defaulted to "persistent"; the "persistent" state is assumed if the attribute is omitted.</td> </tr> <tr> <td><i class="conum" data-value="6"></i><b>6</b></td> <td>Models a list of OIDs. This is used by the <a href="#_rgcms_schema_cmd">"cmd" schema</a> to represent the intention to perform a bulk actions (against a number of selected objects).</td> </tr> </table> </div> <div class="paragraph"> <p>In previous versions of the schema the object type and object identifers of <code>oidDto</code> were modelled as an element rather than an attribute. The element form can still be used, but is deprecated.</p> </div> <div class="paragraph"> <p>The <code>oidDto</code> complex type is used in a number of places by the framework:</p> </div> <div class="ulist"> <ul> <li> <p>first, as a means of serializing JAXB view model/DTOs (annotated with <a href="rgant.html#_rgant-XmlRootElement"><code>@XmlRootElement</code></a>), that reference domain entities.<br></p> <div class="paragraph"> <p>These references are serialized instead into OIDs</p> </div> </li> <li> <p>second, as references to the target of a command representing the <em>intention</em> to invoke an action or edit a property, as described by the <a href="#_rgcms_schema-cmd">"cmd" (command)</a> schema.<br></p> <div class="paragraph"> <p>They are also used to represent references to any action arguments/properties that take domain object entities/view models.</p> </div> </li> <li> <p>third, as references to the target of an interaction capturing the actual execution of an action invocation or property edit, as described by the <a href="#_rgcms_schema-ixn">"ixn" (interaction)</a> schema.</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_rgcms_schema-common_valueDto">4.5.2. <code>valueDto</code> etc</h4> <div class="paragraph"> <p>The common schema also defines two types representing values: the <code>valueDto</code> complex type, the <code>valueType</code> simple type and the <code>valueWithTypeDto</code> complex type:</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span> <span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">valueDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:choice</span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">string</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">byte</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:byte</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">short</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:short</span><span class="delimiter">"</span></span><span class="tag">/></span> ... <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">timestamp</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:dateTime</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">enum</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">enumDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">reference</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">oidDto</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:choice></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:simpleType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">valueType</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:restriction</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">byte</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">short</span><span class="delimiter">"</span></span><span class="tag">/></span> ... <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">enum</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">reference</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">void</span><span class="delimiter">"</span></span><span class="tag">/></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"></xs:restriction></span> <span class="tag"></xs:simpleType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">valueWithTypeDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:complexContent></span> <span class="tag"><xs:extension</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">valueDto</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">type</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">required</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">valueType</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">null</span><span class="delimiter">"</span></span> <span class="attribute-name">use</span>=<span class="string"><span class="delimiter">"</span><span class="content">optional</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:boolean</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:extension></span> <span class="tag"></xs:complexContent></span> <span class="tag"></xs:complexType></span> ... <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>Intended to hold any valid value, eg of an argument to an action or a new value of a property.</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>Enumerates the full set of types understood by the framework; note that these also include references to entities or view models, and to enums.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>Not valid to be used as the parameter type of an action; can be used as its return type.</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>Inherits from <code>valueDto</code>, capturing both a value and its corresponding type. Used for the return value of action invocations, and for the new value in property edits.</td> </tr> </table> </div> <div class="paragraph"> <p>These type definitions are just building blocks, also used within the <a href="#_rgcms_schema-aim">action iInvocation memento</a> schema. The first, <code>valueDto</code> is The second, <code>valueType</code>, enumerates the different types of vales, eg of a formal parameter to an action.</p> </div> </div> <div class="sect3"> <h4 id="_rgcms_schema-common_ancillary">4.5.3. Ancillary types</h4> <div class="paragraph"> <p>The common schema also defines a number of ancillary types, used either by the common schema itself (see above) or by the <a href="#_rgcms_schema_cmd">"cmd"</a> and <a href="#_rgcms_schema_ixn">"ixn"</a> schemas.</p> </div> <div class="listingblock"> <div class="content"> <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><xs:schema</span> <span class="attribute-name">targetNamespace</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span> <span class="attribute-name">...</span> <span class="tag">></span> ... <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">enumDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">enumType</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">enumName</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">periodDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="2"></i><b>(2)</b> <span class="tag"><xs:sequence></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">startedAt</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:dateTime</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:element</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">completedAt</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:dateTime</span><span class="delimiter">"</span></span> <span class="attribute-name">minOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">0</span><span class="delimiter">"</span></span> <span class="attribute-name">maxOccurs</span>=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:sequence></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:complexType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">differenceDto</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="3"></i><b>(3)</b> <span class="tag"><xs:sequence</span><span class="tag">/></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">before</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"><xs:attribute</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">after</span><span class="delimiter">"</span></span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:int</span><span class="delimiter">"</span></span><span class="tag">/></span> <span class="tag"></xs:complexType></span> <span class="tag"><xs:simpleType</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">interactionType</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="4"></i><b>(4)</b> <span class="tag"><xs:restriction</span> <span class="attribute-name">base</span>=<span class="string"><span class="delimiter">"</span><span class="content">xs:string</span><span class="delimiter">"</span></span><span class="tag">></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">action_invocation</span><span class="delimiter">"</span></span> <span class="tag">/></span> <span class="tag"><xs:enumeration</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">property_edit</span><span class="delimiter">"</span></span> <span class="tag">/></span> <span class="tag"></xs:restriction></span> <span class="tag"></xs:simpleType></span> <span class="tag"></xs:schema></span></code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>Models an instance member of an enum (eg <code>Color.RED</code>).</td> </tr> <tr> <td><i class="conum" data-value="2"></i><b>2</b></td> <td>Captures a period of time, eg for capturing metrics/timings.</td> </tr> <tr> <td><i class="conum" data-value="3"></i><b>3</b></td> <td>Captures a pair of numbers representing a difference. Used for example to capture metrics (number objects modified before and after).</td> </tr> <tr> <td><i class="conum" data-value="4"></i><b>4</b></td> <td>Whether this command/interaction with a member is invoking an action, or editing a property. Used by both the <a href="#_rgcms_schema_cmd">"cmd"</a> and <a href="#_rgcms_schema_ixn">"ixn"</a> schemas.</td> </tr> </table> </div> </div> </div> </div> </div> </div> <footer> <hr> <p class="small"> Copyright © 2010~2016 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> </footer> </div> <div id="doc-content-right" class="large-3 medium-3 xcolumns"> <div id="toc" class="toc2"> <div class="fallback-toc"> <ul class="sectlevel1"> <li><a href="#_rgcms">1. Classes, Methods and Schema</a> <ul class="sectlevel2"> <li><a href="#_other_guides">1.1. Other Guides</a></li> </ul> </li> <li><a href="#_rgcms_methods">2. Methods</a> <ul class="sectlevel2"> <li><a href="#_rgcms_methods_prefixes">2.1. Supporting Method Prefixes</a> <ul class="sectlevel3"> <li><a href="#_rgcms_methods_prefixes_addTo">2.1.1. <code>addTo…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_autoComplete">2.1.2. <code>autoComplete…()</code></a> <ul class="sectlevel4"> <li><a href="#_parameters">Parameters</a></li> <li><a href="#_properties">Properties</a></li> </ul> </li> <li><a href="#_rgcms_methods_prefixes_choices">2.1.3. <code>choices…()</code></a> <ul class="sectlevel4"> <li><a href="#_parameters_2">Parameters</a></li> <li><a href="#_properties_2">Properties</a></li> </ul> </li> <li><a href="#_rgcms_methods_prefixes_clear">2.1.4. <code>clear…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_default">2.1.5. <code>default…()</code></a> <ul class="sectlevel4"> <li><a href="#_parameters_3">Parameters</a></li> <li><a href="#_properties_3">Properties</a></li> </ul> </li> <li><a href="#_rgcms_methods_prefixes_disable">2.1.6. <code>disable…()</code></a> <ul class="sectlevel4"> <li><a href="#_actions">Actions</a></li> <li><a href="#_properties_and_collections">Properties and Collections</a></li> </ul> </li> <li><a href="#_rgcms_methods_prefixes_get">2.1.7. <code>get…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_hide">2.1.8. <code>hide…()</code></a> <ul class="sectlevel4"> <li><a href="#_actions_2">Actions</a></li> <li><a href="#_properties_and_collections_2">Properties and Collections</a></li> </ul> </li> <li><a href="#_rgcms_methods_prefixes_modify">2.1.9. <code>modify…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_removeFrom">2.1.10. <code>removeFrom…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_set">2.1.11. <code>set…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_validate">2.1.12. <code>validate…()</code></a> <ul class="sectlevel4"> <li><a href="#_action_parameter">Action Parameter</a></li> <li><a href="#_action_parameter_set">Action Parameter Set</a></li> <li><a href="#_properties_4">Properties</a></li> </ul> </li> <li><a href="#_rgcms_methods_prefixes_validateAddTo">2.1.13. <code>validateAddTo…()</code></a></li> <li><a href="#_rgcms_methods_prefixes_validateRemoveFrom">2.1.14. <code>validateRemoveFrom…()</code></a></li> </ul> </li> <li><a href="#_rgcms_methods_reserved">2.2. Reserved Methods</a> <ul class="sectlevel3"> <li><a href="#_rgcms_methods_reserved_cssClass">2.2.1. <code>cssClass()</code></a></li> <li><a href="#_rgcms_methods_reserved_disable">2.2.2. <code>disable()</code></a> <ul class="sectlevel4"> <li><a href="#_alternatives_2">Alternatives</a></li> </ul> </li> <li><a href="#_rgcms_methods_reserved_getId">2.2.3. <code>getId()</code></a></li> <li><a href="#_rgcms_methods_reserved_hide">2.2.4. <code>hide()</code></a> <ul class="sectlevel4"> <li><a href="#_alternatives_3">Alternatives</a></li> </ul> </li> <li><a href="#_rgcms_methods_reserved_iconName">2.2.5. <code>iconName()</code></a></li> <li><a href="#_rgcms_methods_reserved_title">2.2.6. <code>title()</code></a></li> <li><a href="#_rgcms_methods_reserved_validate">2.2.7. <code>validate()</code></a></li> </ul> </li> <li><a href="#_rgcms_methods_lifecycle">2.3. Lifecycle Methods</a> <ul class="sectlevel3"> <li><a href="#_rgcms_methods_reserved_created">2.3.1. <code>created()</code></a></li> <li><a href="#_rgcms_methods_reserved_loaded">2.3.2. <code>loaded()</code></a></li> <li><a href="#_rgcms_methods_reserved_persisted">2.3.3. <code>persisted()</code></a></li> <li><a href="#_rgcms_methods_reserved_persisting">2.3.4. <code>persisting()</code></a></li> <li><a href="#_rgcms_methods_reserved_removed">2.3.5. <code>removed()</code></a></li> <li><a href="#_rgcms_methods_reserved_removing">2.3.6. <code>removing()</code></a></li> <li><a href="#_rgcms_methods_reserved_updated">2.3.7. <code>updated()</code></a></li> <li><a href="#_rgcms_methods_reserved_updating">2.3.8. <code>updating()</code></a></li> <li><a href="#_rgcms_methods_lifecycle_jdo-api">2.3.9. Using the JDO API</a></li> </ul> </li> </ul> </li> <li><a href="#_rgcms_classes">3. Classes and Interfaces</a> <ul class="sectlevel2"> <li><a href="#_rgcms_classes_AppManifest-bootstrapping">3.1. <code>AppManifest</code> (bootstrapping)</a> <ul class="sectlevel3"> <li><a href="#_api">3.1.1. API</a> <ul class="sectlevel4"> <li><a href="#__code_getmodules_code"><code>getModules()</code></a></li> <li><a href="#__code_getadditionalservices_code"><code>getAdditionalServices()</code></a></li> <li><a href="#__code_getauthenticationmechanism_code"><code>getAuthenticationMechanism()</code></a></li> <li><a href="#__code_getauthorizationmechanism_code"><code>getAuthorizationMechanism()</code></a></li> <li><a href="#__code_getfixtures_code"><code>getFixtures()</code></a></li> <li><a href="#__code_getconfigurationproperties_code"><code>getConfigurationProperties()</code></a></li> </ul> </li> <li><a href="#_bootstrapping">3.1.2. Bootstrapping</a> <ul class="sectlevel4"> <li><a href="#_integration_tests">Integration Tests</a></li> <li><a href="#_webapps">Webapps</a></li> </ul> </li> <li><a href="#_subsidiary_goals">3.1.3. Subsidiary Goals</a></li> </ul> </li> <li><a href="#_rgcms_classes_super">3.2. Superclasses</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_super_AbstractContainedObject">3.2.1. <code>AbstractContainedObject</code></a></li> <li><a href="#_rgcms_classes_super_AbstractDomainObject">3.2.2. <code>AbstractDomainObject</code></a></li> <li><a href="#_rgcms_classes_super_AbstractFactoryAndRepository">3.2.3. <code>AbstractFactoryAndRepository</code></a></li> <li><a href="#_rgcms_classes_super_AbstractService">3.2.4. <code>AbstractService</code></a></li> <li><a href="#_rgcms_classes_super_AbstractSubscriber">3.2.5. <code>AbstractSubscriber</code></a></li> <li><a href="#_rgcms_classes_super_AbstractViewModel">3.2.6. <code>AbstractViewModel</code></a></li> <li><a href="#_rgcms_classes_super_FixtureScript">3.2.7. <code>FixtureScript</code></a></li> <li><a href="#_rgcms_classes_super_FixtureScripts">3.2.8. <code>FixtureScripts</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_domainevent">3.3. Domain Event Classes</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_domainevent_AbstractDomainEvent">3.3.1. <code>AbstractDomainEvent</code></a> <ul class="sectlevel4"> <li><a href="#_api_2">API</a></li> </ul> </li> <li><a href="#_rgcms_classes_domainevent_ActionDomainEvent">3.3.2. <code>ActionDomainEvent</code></a> <ul class="sectlevel4"> <li><a href="#_api_3">API</a></li> </ul> </li> <li><a href="#_rgcms_classes_domainevent_CollectionDomainEvent">3.3.3. <code>CollectionDomainEvent</code></a> <ul class="sectlevel4"> <li><a href="#_api_4">API</a></li> </ul> </li> <li><a href="#_rgcms_classes_domainevent_PropertyDomainEvent">3.3.4. <code>PropertyDomainEvent</code></a> <ul class="sectlevel4"> <li><a href="#_api_5">API</a></li> </ul> </li> </ul> </li> <li><a href="#_rgcms_classes_uievent">3.4. UI Event Classes</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_uievent_TitleUiEvent">3.4.1. <code>TitleUiEvent</code></a></li> <li><a href="#_rgcms_classes_uievent_IconUiEvent">3.4.2. <code>IconUiEvent</code></a></li> <li><a href="#_rgcms_classes_uievent_CssClassUiEvent">3.4.3. <code>CssClassUiEvent</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_lifecycleevent">3.5. Lifecycle Events</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent">3.5.1. <code>AbstractLifecycleEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectCreatedEvent">3.5.2. <code>ObjectCreatedEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectLoadedEvent">3.5.3. <code>ObjectLoadedEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectPersistedEvent">3.5.4. <code>ObjectPersistedEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectPersistingEvent">3.5.5. <code>ObjectPersistingEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectRemovingEvent">3.5.6. <code>ObjectRemovingEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent">3.5.7. <code>ObjectUpdatedEvent</code></a></li> <li><a href="#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent">3.5.8. <code>ObjectUpdatingEvent</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_value-types">3.6. Value Types</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_value-types_Blob">3.6.1. <code>Blob</code></a></li> <li><a href="#_rgcms_classes_value-types_Clob">3.6.2. <code>Clob</code></a></li> <li><a href="#_rgcms_classes_value-types_Color">3.6.3. <code>Color</code></a></li> <li><a href="#_rgcms_classes_value-types_Money">3.6.4. <code>Money</code></a></li> <li><a href="#_rgcms_classes_value-types_Password">3.6.5. <code>Password</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_utility">3.7. Applib Utility Classes</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_utility_Enums">3.7.1. <code>Enums</code></a></li> <li><a href="#_rgcms_classes_utility_ObjectContracts">3.7.2. <code>ObjectContracts</code></a> <ul class="sectlevel4"> <li><a href="#_the_issue_in_more_detail">The issue in more detail</a></li> </ul> </li> <li><a href="#_rgcms_classes_utility_Reasons">3.7.3. <code>Reasons</code></a></li> <li><a href="#_rgcms_classes_utility_TitleBuffer">3.7.4. <code>TitleBuffer</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_spec">3.8. Specification pattern</a> <ul class="sectlevel3"> <li><a href="#__code_specification_code">3.8.1. <code>Specification</code></a></li> <li><a href="#__code_specification2_code">3.8.2. <code>Specification2</code></a></li> <li><a href="#_adapter_classes">3.8.3. Adapter classes</a></li> <li><a href="#_combining_specifications">3.8.4. Combining specifications</a></li> </ul> </li> <li><a href="#_rgcms_classes_i18n">3.9. i18n support</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_i18n_TranslatableString">3.9.1. <code>TranslatableString</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_contributee">3.10. Contributee</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_mixins_HasTransactionId">3.10.1. <code>HasTransactionId</code></a></li> <li><a href="#_rgcms_classes_mixins_HasUserName">3.10.2. <code>HasUsername</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_roles">3.11. Roles</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_roles_HoldsUpdatedAt">3.11.1. <code>HoldsUpdatedAt</code></a> <ul class="sectlevel4"> <li><a href="#_alternative_approaches">Alternative approaches</a></li> </ul> </li> <li><a href="#_rgcms_classes_roles_HoldsUpdatedBy">3.11.2. <code>HoldsUpdatedBy</code></a></li> <li><a href="#_rgcms_classes_roles_Timestampable">3.11.3. <code>Timestampable</code></a> <ul class="sectlevel4"> <li><a href="#_alternatives_4">Alternatives</a></li> </ul> </li> </ul> </li> <li><a href="#_rgcms_classes_mixins">3.12. Mixins</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_mixins_Object">3.12.1. <code>Object</code></a> <ul class="sectlevel4"> <li><a href="#_rgcms_classes_mixins_Object_clearHints"><code>clearHints()</code></a></li> <li><a href="#_rgcms_classes_mixins_Object_downloadLayoutXml"><code>downloadLayoutXml()</code></a></li> <li><a href="#_rgcms_classes_mixins_Object_rebuildMetamodel"><code>rebuildMetamodel()</code></a></li> </ul> </li> <li><a href="#_rgcms_classes_mixins_Dto">3.12.2. <code>Dto</code></a> <ul class="sectlevel4"> <li><a href="#_related_services_4">Related Services</a></li> </ul> </li> <li><a href="#_rgcms_classes_mixins_Persistable">3.12.3. <code>Persistable</code></a> <ul class="sectlevel4"> <li><a href="#_rgcms_classes_mixins_Persistable_downloadJdoMetadata"><code>downloadJdoMetadata()</code></a></li> <li><a href="#_rgcms_classes_mixins_Persistable_datanucleusXxx"><code>datanucleusXxx</code></a></li> </ul> </li> </ul> </li> <li><a href="#_rgcms_classes_layout">3.13. Layout</a> <ul class="sectlevel3"> <li><a href="#_rgcms_classes_layout_component">3.13.1. Component</a></li> <li><a href="#_rgcms_classes_layout_grid-bootstrap3">3.13.2. Bootstrap3 Grid</a></li> </ul> </li> </ul> </li> <li><a href="#_rgcms_schema">4. Schema</a> <ul class="sectlevel2"> <li><a href="#_rgcms_schema-cmd">4.1. Command</a> <ul class="sectlevel3"> <li><a href="#_rgcms_schema-cmd_commandDto">4.1.1. <code>commandDto</code></a></li> <li><a href="#_rgcms_schema-cmd_memberDto">4.1.2. <code>memberDto</code> and subtypes</a></li> <li><a href="#_rgcms_schema-cmd_ancillary">4.1.3. Ancillary types</a></li> </ul> </li> <li><a href="#_rgcms_schema-ixn">4.2. Interaction Execution</a> <ul class="sectlevel3"> <li><a href="#_rgcms_schema-ixn_interactionDto">4.2.1. <code>interactionDto</code></a></li> <li><a href="#_rgcms_schema-ixn_memberExecutionDto">4.2.2. <code>memberExecutionDto</code></a></li> <li><a href="#_rgcms_schema-ixn_ancillary">4.2.3. Ancillary types</a></li> </ul> </li> <li><a href="#_rgcms_schema-chg">4.3. Changes</a> <ul class="sectlevel3"> <li><a href="#__code_changesdto_code">4.3.1. <code>changesDto</code></a></li> <li><a href="#__code_objectsdto_code">4.3.2. <code>objectsDto</code></a></li> </ul> </li> <li><a href="#_rgcms_schema-aim">4.4. Action Invocation Memento</a></li> <li><a href="#_rgcms_schema-common">4.5. Common Schema</a> <ul class="sectlevel3"> <li><a href="#_rgcms_schema-common_oidDto">4.5.1. <code>oidDto</code></a></li> <li><a href="#_rgcms_schema-common_valueDto">4.5.2. <code>valueDto</code> etc</a></li> <li><a href="#_rgcms_schema-common_ancillary">4.5.3. Ancillary types</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </div> <script src="../js/foundation/5.5.1/vendor/jquery.js"></script> <script src="../js/foundation/5.5.1/foundation.min.js"></script> <link href="../css/jquery.tocify/1.9.0/jquery.tocify.css" rel="stylesheet"> <script src="../js/jqueryui/1.11.4/jquery-ui.min.js"></script> <script src="../js/jquery.tocify/1.9.0/jquery.tocify.js"></script> <script type="text/javascript"> $(function () { $("#toc").tocify({ scrollTo: 50, extendPage: true, context: "#doc-content", highlightOnScroll: true, hashGenerator: "pretty", hideEffect: "slideUp", selectors: "h2,h3,h4,h5" }); $(".fallback-toc").hide(); }); </script> <script type="text/javascript"> /**** $(document).foundation(); $(document).ready(function(){ // Cache selectors var lastId, topMenu = $("div#toc ul"), topMenuHeight = 100, menuItems = topMenu.find("a"), menuItemsHrefs = menuItems.map(function(){ var item = $($(this).attr("href")); if (item.length) { return item; } }); // Bind click handler to menu items to scroll animation menuItems.click(function(e){ var href = $(this).attr("href"), offsetTop = href === "#" ? 0 : $(href).offset().top-topMenuHeight+1; $('html, body').stop().animate({ scrollTop: offsetTop }, 300); e.preventDefault(); }); // Bind to scroll of window $( window ).scroll(function(){ // Get container scroll position var fromTop = $(this).scrollTop()+topMenuHeight; var cur = menuItemsHrefs.map(function(){ if ($(this).offset().top < fromTop) return this; }); // Get the id of the current element cur = cur[cur.length-1]; var id = cur && cur.length ? cur[0].id : ""; if (lastId !== id && id) { scrollTo(id); } window.history.pushState({}, "", window.location.origin + window.location.pathname + "#" + id); }); scrollTo = function(id) { lastId = id; menuItems .removeClass("active"); menuItems .parents() .removeClass("active-region"); menuItems .parents("ul").hide(); menuItems .filter("[href=#"+id+"]") .addClass("active"); menuItems .filter("[href=#"+id+"]") .parents("ul").show(); menuItems .filter("[href=#"+id+"]") .parent().children("ul").show(); menuItems .filter("[href=#"+id+"]") .parents("li").addClass("active-region"); } menuItems .removeClass("active"); menuItems .parents() .removeClass("active-region"); var syncMenuItem; if(window.location.hash!=="") { var menuItemFor = $.grep(menuItems, function(e) { return e.hash === window.location.hash; }); console.log(menuItemFor); if(menuItemFor.length === 1) { syncMenuItem = menuItemFor[0]; } } if(!syncMenuItem){ syncMenuItem = menuItems[0]; } $(syncMenuItem).click(); }); ***/ </script> <script type="text/javascript"> $(document).ready(function(){ if("Documentation" === "Classes, Methods and Schema") { console.log( "processing 'Documentation'" ); $("#doc-content-left").removeClass("large-9").removeClass("medium-9").addClass("large-12").addClass("medium-12"); $("#doc-content-right").removeClass("large-3").removeClass("medium-3").hide(); } }); </script> <script> $( document ).ready(function() { (function() { $(function() { return $("#doc-content h2, #doc-content h3, #doc-content h4, #doc-content h5, #doc-content h6").each(function(i, el) { var $el, icon, id; $el = $(el); id = $el.attr('id'); icon = '<i class="fa fa-link"></i>'; if (id) { return $el.prepend($("<a />").addClass("header-link").attr("href", "#" + id).html(icon)); } }); }); }).call(this); /* http://osvaldas.info/auto-hide-sticky-header MIT license */ ;( function( $, window, document, undefined ) { 'use strict'; var elSelector = '.header', elClassHidden = 'header--hidden', throttleTimeout = 500, $element = $( elSelector ); if( !$element.length ) return true; var $window = $( window ), wHeight = 0, wScrollCurrent = 0, wScrollBefore = 0, wScrollDiff = 0, $document = $( document ), dHeight = 0, throttle = function( delay, fn ) { var last, deferTimer; return function() { var context = this, args = arguments, now = +new Date; if( last && now < last + delay ) { clearTimeout( deferTimer ); deferTimer = setTimeout( function(){ last = now; fn.apply( context, args ); }, delay ); } else { last = now; fn.apply( context, args ); } }; }; $window.on( 'scroll', throttle( throttleTimeout, function() { dHeight = $document.height(); wHeight = $window.height(); wScrollCurrent = $window.scrollTop(); wScrollDiff = wScrollBefore - wScrollCurrent; if( wScrollCurrent <= 0 ) // scrolled to the very top; element sticks to the top $element.removeClass( elClassHidden ); else if( wScrollDiff > 0 && $element.hasClass( elClassHidden ) ) // scrolled up; element slides in $element.removeClass( elClassHidden ); else if( wScrollDiff < 0 ) // scrolled down { if( wScrollCurrent + wHeight >= dHeight && $element.hasClass( elClassHidden ) ) // scrolled to the very bottom; element slides in $element.removeClass( elClassHidden ); else // scrolled down; element slides out $element.addClass( elClassHidden ); } wScrollBefore = wScrollCurrent; })); })( jQuery, window, document ); }); </script> </body> </html>

content/versions/1.13.2.1/guides/rgcms.html (7,182 lines of code) (raw):