You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2012/12/21 12:00:39 UTC
svn commit: r1424863 [2/3] - in /isis/site/trunk/content:
contributors/updating-the-applib-docs.md core/guides/isis-applib.html
core/guides/isis-applib.pdf
Modified: isis/site/trunk/content/core/guides/isis-applib.html
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/core/guides/isis-applib.html?rev=1424863&r1=1424862&r2=1424863&view=diff
==============================================================================
--- isis/site/trunk/content/core/guides/isis-applib.html (original)
+++ isis/site/trunk/content/core/guides/isis-applib.html Fri Dec 21 11:00:38 2012
@@ -8,48 +8,46 @@
<p>Permission is granted to make and distribute verbatim copies of
this manual provided that the copyright notice and this permission
notice are preserved on all copies.</p>
- </div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#preface">Preface</a></span></dt><dt><span class="chapter"><a href="#d5e26">1. Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e30">What's in this Guide</a></span></dt><dt><span class="sect1"><a href="#d5e40">This Guide vs the Core Documentation</a></span></dt><dt><span class="sect1"><a href="#d5e56">Where Next?</a></span></dt></dl></dd><dt><span class="part"><a href="#prt.UnderstandingApacheIsis">I. Understanding Apache Isis</a></span></dt><dd><dl><dt><span class="chapter"><a href="#chp.PrinciplesAndPatterns">2. Apache Isis and Naked Objects</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e84">Apache Isis implements the naked objects pattern... but what is
- that, exactly?</a></span></dt><dt><span class="sect1"><a href="#d5e91">What type of applications are best suited to Isis?</a></span></dt><dt><span class="sect1"><a href="#d5e99">And are there applications where the OO UIs generated by Isis
- are less suitable?</a></span></dt><dt><span class="sect1"><a href="#d5e112">What is the typical development process life cycle for
- applications built with Isis, and how does it compare to traditional
- application development process?</a></span></dt><dt><span class="sect1"><a href="#d5e144">What are the limitations of Apache Isis framework?</a></span></dt><dt><span class="sect1"><a href="#d5e172">How extensive is the application security support provided by
- Isis?</a></span></dt><dt><span class="sect1"><a href="#d5e187">How does an Isis applications manage the custom logic in terms
- of business rules, workflow and other business logic that developers
- have to manually implement outside the generated code?</a></span></dt><dt><span class="sect1"><a href="#d5e192">How does Isis support SOA-based applications, eg where an
- enterprise service component is consumed by several different
- applications and other clients?</a></span></dt><dt><span class="sect1"><a href="#d5e208">Most enterprise applications need to reuse the domain and
- service layer classes between several different applications. How does
- Apache Isis address this?</a></span></dt><dt><span class="sect1"><a href="#d5e225">What is the future road map of the project?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.DevelopmentProcess">3. A Development Process</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.ApplicationArchetypes">Run the Quickstart Archetype</a></span></dt><dt><span class="sect1"><a href="#d5e250">Programming Model</a></span></dt><dt><span class="sect1"><a href="#d5e258">Fixtures and Prototyping</a></span></dt><dt><span class="sect1"><a href="#sec.Viewers">Viewers</a></span></dt><dt><span class="sect1"><a href="#sec.AgileTesting">Agile Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec.BddTesting">Story (BDD) Testing</a></span></dt><dt><span class="sect2"><a href="#sec.UnitTesting">Unit Testing</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e322">A Domain Library</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e331">Do
main Services</a></span></dt><dt><span class="sect2"><a href="#d5e343">Domain Values</a></span></dt><dt><span class="sect2"><a href="#d5e355">Domain Entities</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DeployingAnIsisApplication">Deploying an Isis Application</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e365">Persistence (the Default Runtime / Object Store)</a></span></dt><dt><span class="sect2"><a href="#d5e398">Authentication and Authorization</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="#prt.WritingDomainObjects">II. Writing Domain Objects</a></span></dt><dd><dl><dt><span class="chapter"><a href="#chp.Objects">4. Domain Entities</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e429">How to not inherit from framework superclasses</a></span></dt><dt><span class="sect1"><a href="#d5e440">How to specify a title for an object</a></span></dt><dt><span class="sect1"><a href="#sec.HowToSpecifyTheIconForAnO
bjectsClass">How to specify the icon for an object's
- class</a></span></dt><dt><span class="sect1"><a href="#d5e483">How to specify the icon for an individual object's
- state</a></span></dt><dt><span class="sect1"><a href="#d5e494">How to specify a name and/or description for an
- object</a></span></dt><dt><span class="sect1"><a href="#d5e506">How to specify that an object should not be
- persisted</a></span></dt><dt><span class="sect1"><a href="#sec.Immutable">How to specify that an object should
- never be modified by the user</a></span></dt><dt><span class="sect1"><a href="#sec.Entity.Disabled">How to control when an object can be modified</a></span></dt><dt><span class="sect1"><a href="#sec.Entity.Hidden">How to control when an object is visible</a></span></dt><dt><span class="sect1"><a href="#sec.Bounded">How to specify that a class of objects has a limited number of
- instances</a></span></dt><dt><span class="sect1"><a href="#sec.HowToCreateAnObject">How to create or delete objects within your code</a></span></dt><dt><span class="sect1"><a href="#sec.LifecycleMethods">How to insert behaviour into the object life cycle</a></span></dt><dt><span class="sect1"><a href="#sec.ResolveAndObjectChanged">How to perform lazy loading (generally done
- automatically)</a></span></dt><dt><span class="sect1"><a href="#d5e687">How to perform dirty object tracking (generally done
- automatically)</a></span></dt><dt><span class="sect1"><a href="#d5e696">How to ensure object is in valid state</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Properties">5. Domain Entity Properties</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e720">How to add a property to an object</a></span></dt><dt><span class="sect1"><a href="#d5e739">How to specify a name and/or description for a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e741">Specifying the name for a property</a></span></dt><dt><span class="sect2"><a href="#d5e747">Specifying a description for a property</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.MemberOrderForProperties">How to specify the order in which properties are
- displayed</a></span></dt><dt><span class="sect1"><a href="#d5e761">How to make a property optional (when saving an object)</a></span></dt><dt><span class="sect1"><a href="#sec.SizeProperties">How to specify the size of <code class="classname">String</code>
- properties</a></span></dt><dt><span class="sect1"><a href="#sec.DerivedProperty">How to make a derived property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e786">Lazily derived</a></span></dt><dt><span class="sect2"><a href="#d5e797">Eagerly derived</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.HiddenProperty">How to hide a property from the user</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e813">Hiding a property always</a></span></dt><dt><span class="sect2"><a href="#d5e819">Hiding a property based on the persistence state of the
- object</a></span></dt><dt><span class="sect2"><a href="#d5e830">Hiding a property under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e841">Hiding a property for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledProperty">How to prevent a property from being modified</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e854">Disabling a property permanently</a></span></dt><dt><span class="sect2"><a href="#d5e861">Disabling a property based on the persistence state of the
- object</a></span></dt><dt><span class="sect2"><a href="#d5e872">Disabling a property under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e885">Disabling a property for certain users/roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e890">How to validate user input for a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e892">Declarative validation</a></span></dt><dt><span class="sect2"><a href="#d5e907">Imperative validation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DefaultPropertyValue">How to set up the initial value of a property
- programmatically</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e924">By each property's default values</a></span></dt><dt><span class="sect2"><a href="#d5e933">By the <code class="methodname">created()</code> lifecycle
- method</a></span></dt><dt><span class="sect2"><a href="#d5e940">Programmatically, by the creator</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e946">How to specify a set of choices for a property</a></span></dt><dt><span class="sect1"><a href="#sec.ModifyAndClear">How to trigger other behaviour when a property is
- changed</a></span></dt><dt><span class="sect1"><a href="#d5e983">How to setup a bidirectional relationship</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Collections">6. Domain Entity Collections</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1000">How to add a collection to an object</a></span></dt><dt><span class="sect1"><a href="#d5e1024">How to specify a name and/or description for a
- collection</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1026">Specifying the name for a collection</a></span></dt><dt><span class="sect2"><a href="#d5e1032">Specifying a description for a collection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.MemberOrderForCollections">How to specify the order in which collections are
- displayed</a></span></dt><dt><span class="sect1"><a href="#d5e1046">How to make a derived collection</a></span></dt><dt><span class="sect1"><a href="#sec.HiddenCollection">How to hide a collection</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1059">Hiding a collection permanently</a></span></dt><dt><span class="sect2"><a href="#d5e1065">Hiding a collection based on the persistence state of the
- object</a></span></dt><dt><span class="sect2"><a href="#d5e1076">Hiding a collection under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e1087">Hiding a collection for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledCollection">How to prevent a collection from being modified</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1098">Disabling a collection permanently</a></span></dt><dt><span class="sect2"><a href="#d5e1107">Disabling a collection based on the persistence state of the
- object</a></span></dt><dt><span class="sect2"><a href="#d5e1118">Disabling a collection under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e1127">Disabling a collection for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1132">How to validate an object being added or removed</a></span></dt><dt><span class="sect1"><a href="#sec.AddToRemoveFrom">How to trigger other behaviour when an object is added or
- removed</a></span></dt><dt><span class="sect1"><a href="#sec.MutualRegistrationPattern">How to maintain bidirectional relationships</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Actions">7. Domain Entity Actions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1185">How to add an action to an object</a></span></dt><dt><span class="sect1"><a href="#d5e1215">How to specify names and/or description for an action</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1217">Specifying the name for an action</a></span></dt><dt><span class="sect2"><a href="#d5e1223">Specifying a description for a collection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1229">How to specify the order in which actions appear on the
- menu</a></span></dt><dt><span class="sect1"><a href="#sec.HiddenActions">How to hide an action</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1240">Hiding an action permanently</a></span></dt><dt><span class="sect2"><a href="#d5e1247">Hiding an action based on the persistence state of the
- object</a></span></dt><dt><span class="sect2"><a href="#d5e1258">Hiding an action under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e1274">Hiding an action for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledAction">How to prevent an action from being invoked</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1285">Disabling an action permanently</a></span></dt><dt><span class="sect2"><a href="#d5e1289">Disabling an action based on the persistence state of the
- object</a></span></dt><dt><span class="sect2"><a href="#d5e1301">Based on the state of the object</a></span></dt><dt><span class="sect2"><a href="#d5e1313">Disabling an action for certain users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1318">How to specify names and/or descriptions for an action
- parameter</a></span></dt><dt><span class="sect1"><a href="#d5e1329">How to specify the size of <code class="classname">String</code> action
- parameters</a></span></dt><dt><span class="sect1"><a href="#d5e1348">How to make an action parameter optional</a></span></dt><dt><span class="sect1"><a href="#d5e1352">How to validate an action parameter argument</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1354">Declarative validation</a></span></dt><dt><span class="sect2"><a href="#d5e1369">Imperative validation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1383">How to specify default values for an action parameter</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1387">Per-parameter syntax (preferred)</a></span></dt><dt><span class="sect2"><a href="#d5e1394">All parameters syntax</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1402">How to specify a set of choices for an action parameter</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1408">Per parameter syntax (preferred)</a></span></dt><dt><span class="sect2"><a href="#d5e1416">All parameters sy
ntax</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d5e1425">8. Further Business Rule How-Tos</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.MustSpecify">@MustSatisfy Specification</a></span></dt><dt><span class="sect1"><a href="#sec.BusinessRulesForCertainUsersOrRoles">Hiding, disabling or validating for specific users or
- roles</a></span></dt><dt><span class="sect1"><a href="#d5e1478">How to pass a messages and errors back to the user</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.DomainServices">9. Domain Services, Repositories and Factories</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.AbstractService">How to not inherit from framework classes</a></span></dt><dt><span class="sect1"><a href="#sec.Services">How to register domain services, repositories and
- factories</a></span></dt><dt><span class="sect1"><a href="#d5e1528">How to inject services into entities</a></span></dt><dt><span class="sect1"><a href="#d5e1535">How to write a typical domain service</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1542">The <code class="methodname">getId()</code> method</a></span></dt><dt><span class="sect2"><a href="#d5e1550">(Suppressing) contributed actions</a></span></dt><dt><span class="sect2"><a href="#d5e1572">(Suppressing) service menu items</a></span></dt><dt><span class="sect2"><a href="#d5e1581">(Suppressing) service menus</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1586">How to use a generic repository</a></span></dt><dt><span class="sect1"><a href="#sec.CustomRepository">How to write a custom repository</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1634">Finding by Title</a></span></dt><dt><span class="sect2"><a href="#d5e1650">Finding by Pattern</a></span></dt><dt><span class
="sect2"><a href="#d5e1672">Finding using the <code class="classname">Filter</code> API</a></span></dt><dt><span class="sect2"><a href="#d5e1695">Finding using the <code class="classname">Query</code> API</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1739">Factories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.ValueTypes">10. Value Types</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1781">Built-in Value Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1785">JDK Types</a></span></dt><dt><span class="sect2"><a href="#d5e1863">Value formats</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1960">Custom Value Types</a></span></dt><dt><span class="sect1"><a href="#d5e1999">Third-party Value Types</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#prt.SupportingFeatures">III. Supporting Features</a></span></dt><dd><dl><dt><span class="chapter"><a href="#chp.Clock">11. Clock</a></span></
dt><dd><dl><dt><span class="sect1"><a href="#d5e2030">Lazily Instantiated</a></span></dt><dt><span class="sect1"><a href="#d5e2039">Possibly Replaceable</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.UserProfiles">12. Profiles</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e2053">Profiles and Perspectives</a></span></dt><dt><span class="sect1"><a href="#d5e2076">Runtime and Viewer Support</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Fixtures">13. Fixtures and SwitchUser</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.HowToRegisterFixtures">How to register fixtures</a></span></dt><dt><span class="sect1"><a href="#d5e2107">How to write custom fixtures</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2113"><code class="classname">InstallableFixture</code> and
- <code class="classname">FixtureType</code></a></span></dt><dt><span class="sect2"><a href="#d5e2133"><code class="classname">BaseFixture</code> and
- <code class="classname">AbstractFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e2166"><code class="methodname">DateFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e2177"><code class="methodname">SwitchUserFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e2197"><code class="classname">LogonFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e2204"><code class="classname">UserProfileFixture</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chp.XmlSnapshots">14. XML Snapshots</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e2234">Generating an XML Snapshot</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2238">Basic Usage</a></span></dt><dt><span class="sect2"><a href="#d5e2247">Including other Elements</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e2263">Using the Fluent API</a></span></dt><dt><span class="sect1"><a href="#d5e2268">The
<code class="classname">SnapshottableWithInclusions</code>
- interface</a></span></dt><dt><span class="sect1"><a href="#d5e2277">Generating an XSD schema</a></span></dt><dt><span class="sect1"><a href="#d5e2284">Hints and Tips</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#prt.ReferenceAppendices">IV. Reference Appendices</a></span></dt><dd><dl><dt><span class="appendix"><a href="#d5e2296">A. Recognized Methods and Prefixes</a></span></dt><dt><span class="appendix"><a href="#d5e2568">B. Recognized Annotations</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e2575">@ActionOrder</a></span></dt><dt><span class="sect1"><a href="#d5e2594">@ActionSemantics</a></span></dt><dt><span class="sect1"><a href="#d5e2604">@AutoComplete</a></span></dt><dt><span class="sect1"><a href="#d5e2613">@Aggregated</a></span></dt><dt><span class="sect1"><a href="#d5e2621">@Bounded</a></span></dt><dt><span class="sect1"><a href="#sec.DebugAnnotation">@Debug</a></span></dt><dt><span class="sect1"><a href="#d5e2640">@Default
ed</a></span></dt><dt><span class="sect1"><a href="#d5e2650">@DescribedAs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2658">Providing a description for an object</a></span></dt><dt><span class="sect2"><a href="#d5e2664">Providing a description for an object member</a></span></dt><dt><span class="sect2"><a href="#d5e2670">Providing a description for an action parameter</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e2676">@Disabled</a></span></dt><dt><span class="sect1"><a href="#d5e2745">@Encodable</a></span></dt><dt><span class="sect1"><a href="#d5e2755">@EqualByContent</a></span></dt><dt><span class="sect1"><a href="#d5e2764">@Executed</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2770">Forcing a method to be executed on the client</a></span></dt><dt><span class="sect2"><a href="#d5e2774">Forcing a method to be executed on the server</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.ExplorationAnnotation">@Exploratio
n</a></span></dt><dt><span class="sect1"><a href="#d5e2789">@Facets</a></span></dt><dt><span class="sect1"><a href="#d5e2798">@FieldOrder</a></span></dt><dt><span class="sect1"><a href="#sec.HiddenAnnotation">@Hidden</a></span></dt><dt><span class="sect1"><a href="#d5e2882">@Idempotent (deprecated)</a></span></dt><dt><span class="sect1"><a href="#d5e2886">@Ignore (deprecated)</a></span></dt><dt><span class="sect1"><a href="#d5e2893">@Immutable</a></span></dt><dt><span class="sect1"><a href="#sec.MaskAnnotation">@Mask</a></span></dt><dt><span class="sect1"><a href="#sec.MaxLengthAnnotation">@MaxLength</a></span></dt><dt><span class="sect1"><a href="#sec.MemberGroupsAnnotation">@MemberGroups</a></span></dt><dt><span class="sect1"><a href="#sec.MemberOrderAnnotation">@MemberOrder</a></span></dt><dt><span class="sect1"><a href="#d5e2984">@MultiLine</a></span></dt><dt><span class="sect1"><a href="#d5e3015">@MustSatisfy</a></span></dt><dt><span class="sect1"><a href="#sec.NamedAnn
otation">@Named</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e3039">Specifying the name of an object</a></span></dt><dt><span class="sect2"><a href="#d5e3048">Specifying the name of a class member</a></span></dt><dt><span class="sect2"><a href="#d5e3057">Specifying the name for an action parameter</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.NotContributedAnnotation">@NotContributed</a></span></dt><dt><span class="sect1"><a href="#sec.NotInServiceMenuAnnotation">@NotInServiceMenu</a></span></dt><dt><span class="sect1"><a href="#not-persistable">@NotPersistable</a></span></dt><dt><span class="sect1"><a href="#d5e3108">@NotPersisted</a></span></dt><dt><span class="sect1"><a href="#d5e3116">@ObjectType</a></span></dt><dt><span class="sect1"><a href="#d5e3126">@Optional</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e3135">Making a property optional</a></span></dt><dt><span class="sect2"><a href="#d5e3144">Making an action parameter op
tional</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e3149">@Paged</a></span></dt><dt><span class="sect1"><a href="#d5e3164">@Parseable</a></span></dt><dt><span class="sect1"><a href="#sec.PluralAnnotation">@Plural</a></span></dt><dt><span class="sect1"><a href="#d5e3184">@Programmatic</a></span></dt><dt><span class="sect1"><a href="#sec.PrototypeAnnotation">@Prototype</a></span></dt><dt><span class="sect1"><a href="#d5e3206">@QueryOnly (deprecated)</a></span></dt><dt><span class="sect1"><a href="#sec.RegExAnnotation">@RegEx</a></span></dt><dt><span class="sect1"><a href="#d5e3227">@Resolve</a></span></dt><dt><span class="sect1"><a href="#sec.TitleAnnotation">@Title</a></span></dt><dt><span class="sect1"><a href="#d5e3258">@TypeOf</a></span></dt><dt><span class="sect1"><a href="#d5e3266">@TypicalLength</a></span></dt><dt><span class="sect1"><a href="#sec.ValueAnnotation">@Value</a></span></dt><dt><span class="sect1"><a href="#d5e3292">@ViewModel</a></span></dt
></dl></dd><dt><span class="appendix"><a href="#apx.DomainObjectContainer">C. <code class="classname">DomainObjectContainer</code> interface</a></span></dt><dt><span class="appendix"><a href="#apx.SecurityClasses">D. Security Classes</a></span></dt><dt><span class="appendix"><a href="#apx.UtilityClasses">E. Utility Classes</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e3499">Title creation</a></span></dt><dt><span class="sect1"><a href="#d5e3506">Reason text creation (for disable and validate methods)</a></span></dt></dl></dd><dt><span class="appendix"><a href="#d5e3521">F. Events</a></span></dt><dt><span class="appendix"><a href="#d5e3532">G. Package Dependencies</a></span></dt></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>4.1. <a href="#d5e627">Object lifecycle methods</a></dt><dt>A.1. <a href="#d5e2300">Recognized Method Prefixes</a></dt><dt>A.2. <a href="#d5e2513">Deprecated Method Prefixes</a></dt><dt>C.1. <a href="#d5
e3310">DomainObjectContainer methods (1 of 2)</a></dt><dt>C.2. <a href="#d5e3375">DomainObjectContainer methods (2 of 2)</a></dt></dl></div>
+ </div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#preface">Preface</a></span></dt><dt><span class="part"><a href="#prt.WritingDomainObjects">I. Writing Domain Objects</a></span></dt><dd><dl><dt><span class="chapter"><a href="#chp.Objects">1. How to write a basic Domain Entity or Service</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e44">How to have a domain entity be a POJO (not inherit from
+ framework superclasses)</a></span></dt><dt><span class="sect1"><a href="#sec.AbstractService">How to have a domain service be a POJO (not inherit from
+ framework superclasses)</a></span></dt><dt><span class="sect1"><a href="#d5e71">How to add a property to a domain entity</a></span></dt><dt><span class="sect1"><a href="#d5e91">How to add a collection to a domain entity</a></span></dt><dt><span class="sect1"><a href="#d5e119">How to add an action to a domain entity or service</a></span></dt><dt><span class="sect1"><a href="#d5e150">How to specify a title for a domain
+ entity</a></span></dt><dt><span class="sect1"><a href="#sec.HowToSpecifyTheIconForAnObjectsClass">How to specify the icon for a domain
+ entity</a></span></dt><dt><span class="sect1"><a href="#sec.MemberOrderForProperties">How to specify the order in which properties or collections are
+ displayed</a></span></dt><dt><span class="sect1"><a href="#d5e200">How to specify the order in which actions appear on the
+ menu</a></span></dt><dt><span class="sect1"><a href="#d5e209">How to make a property optional (when saving an object)</a></span></dt><dt><span class="sect1"><a href="#d5e214">How to make an action parameter optional</a></span></dt><dt><span class="sect1"><a href="#sec.SizeProperties">How to specify the size of <code class="classname">String</code>
+ properties</a></span></dt><dt><span class="sect1"><a href="#d5e236">How to specify the size of <code class="classname">String</code> action
+ parameters</a></span></dt><dt><span class="sect1"><a href="#sec.ActionParameterNames">How to specify names and/or descriptions for an action
+ parameter</a></span></dt><dt><span class="sect1"><a href="#d5e266">How to inject services into a domain entity or other
+ service</a></span></dt><dt><span class="sect1"><a href="#sec.HowToCreateAnObject">How to create or delete objects within your code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Properties">2. How to add business rules</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.HiddenProperty">How to hide a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e350">Hiding a property always</a></span></dt><dt><span class="sect2"><a href="#d5e356">Hiding a property based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e367">Hiding a property under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e378">Hiding a property for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.HiddenCollection">How to hide a collection</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e388">Hiding a collection permanently</a></span></dt><dt><span class="sect2"><a href="#d5e394">Hiding a collection based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e405">Hiding a collection under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e416">Hiding a collection for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.HiddenActions">How to hide an action</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e426">Hiding an action permanently</a></span></dt><dt><span class="sect2"><a href="#d5e433">Hiding an action based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e444">Hiding an action under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e455">Hiding an action for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.Entity.Hidden">How to specify that none of an object's members is
+ visible</a></span></dt><dt><span class="sect1"><a href="#sec.DisabledProperty">How to prevent a property from being modified</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e474">Disabling a property permanently</a></span></dt><dt><span class="sect2"><a href="#d5e481">Disabling a property based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e492">Disabling a property under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e505">Disabling a property for certain users/roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledCollection">How to prevent a collection from being modified</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e516">Disabling a collection permanently</a></span></dt><dt><span class="sect2"><a href="#d5e525">Disabling a collection based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e536">Disabling a collection under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e545">Disabling a collection for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledAction">How to prevent an action from being invoked</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e556">Disabling an action permanently</a></span></dt><dt><span class="sect2"><a href="#d5e560">Disabling an action based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e572">Based on the state of the object</a></span></dt><dt><span class="sect2"><a href="#d5e584">Disabling an action for certain users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.Entity.Disabled">How to specify that none of an object's members can be
+ modified/invoked</a></span></dt><dt><span class="sect1"><a href="#sec.Immutable">How to specify that an object is
+ immutable (that none of its members can ever be modified)</a></span></dt><dt><span class="sect1"><a href="#d5e614">How to validate user input for a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e616">Declarative validation</a></span></dt><dt><span class="sect2"><a href="#d5e631">Imperative validation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e644">How to validate an object being added or removed from a
+ collection</a></span></dt><dt><span class="sect1"><a href="#d5e659">How to validate an action parameter argument</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e661">Declarative validation</a></span></dt><dt><span class="sect2"><a href="#d5e676">Imperative validation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.MustSpecify">How to validate declaratively using @MustSatisfy</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e722">3. How to provide drop-downs and default values</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e728">How to specify a set of choices for a property</a></span></dt><dt><span class="sect1"><a href="#d5e745">How to specify a set of choices for an action parameter</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e751">Per parameter syntax (preferred)</a></span></dt><dt><span class="sect2"><a href="#d5e759">All parameters syntax</a></span></dt></dl></dd><dt><span class="sect1"><a href=
"#sec.Bounded">How to specify that a class of objects has a limited number of
+ instances</a></span></dt><dt><span class="sect1"><a href="#d5e779">How to find an entity (for an action parameter or property)
+ using auto-complete</a></span></dt><dt><span class="sect1"><a href="#d5e791">How to specify default values for an action parameter</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e795">Per-parameter syntax (preferred)</a></span></dt><dt><span class="sect2"><a href="#d5e802">All parameters syntax</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d5e810">4. How to derive properties and collections, and other
+ side-effects</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.DerivedProperty">How to make a derived property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e818">Read-only</a></span></dt><dt><span class="sect2"><a href="#d5e825">Read-write</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DerivedCollection">How to make a derived collection</a></span></dt><dt><span class="sect1"><a href="#d5e849">How to inline the results of a query-only repository
+ action</a></span></dt><dt><span class="sect1"><a href="#sec.ModifyAndClear">How to trigger other behaviour when a property is
+ changed</a></span></dt><dt><span class="sect1"><a href="#sec.AddToRemoveFrom">How to trigger other behaviour when an object is added or
+ removed</a></span></dt><dt><span class="sect1"><a href="#sec.MutualRegistrationPattern">How to set up and maintain bidirectional relationships</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e919">5. How to provide additional UI hints</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e927">How to specify a name and/or description for an
+ object</a></span></dt><dt><span class="sect1"><a href="#d5e939">How to specify a name and/or description for a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e941">Specifying the name for a property</a></span></dt><dt><span class="sect2"><a href="#d5e947">Specifying a description for a property</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e953">How to specify a name and/or description for a
+ collection</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e955">Specifying the name for a collection</a></span></dt><dt><span class="sect2"><a href="#d5e961">Specifying a description for a collection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e967">How to specify names and/or description for an action</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e969">Specifying the name for an action</a></span></dt><dt><span class="sect2"><a href="#d5e975">Specifying a description for a collection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e981">How to specify the icon for an individual object's
+ state</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e992">6. How to deal with errors</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.passMessagesAndErrors">How to pass a messages and errors back to the user</a></span></dt><dt><span class="sect1"><a href="#d5e1017">How to deal with an unexpected error</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e1024">7. How to handle entity persistence lifecycle</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.DefaultPropertyValue">How to set up the initial value of a property
+ programmatically</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1033">By each property's default values</a></span></dt><dt><span class="sect2"><a href="#d5e1042">By the <code class="methodname">created()</code> lifecycle
+ method</a></span></dt><dt><span class="sect2"><a href="#d5e1049">Programmatically, by the creator</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.LifecycleMethods">How to insert behaviour into the object life cycle</a></span></dt><dt><span class="sect1"><a href="#d5e1114">How to ensure object is in valid state</a></span></dt><dt><span class="sect1"><a href="#d5e1133">How to specify that an object should not be
+ persisted</a></span></dt><dt><span class="sect1"><a href="#sec.ResolveAndObjectChanged">How to perform lazy loading (generally done
+ automatically)</a></span></dt><dt><span class="sect1"><a href="#d5e1150">How to perform dirty object tracking (generally done
+ automatically)</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e1159">8. How to handle security concerns</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.BusinessRulesForCertainUsersOrRoles">Hiding, disabling or validating for specific users or
+ roles</a></span></dt><dt><span class="sect1"><a href="#d5e1180">How to use Isis' authorization manager</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.DomainServices">9. Domain Services, Repositories and Factories</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.Services">How to register domain services, repositories and
+ factories</a></span></dt><dt><span class="sect1"><a href="#d5e1208">How to write a typical domain service</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1215">The <code class="methodname">getId()</code> method</a></span></dt><dt><span class="sect2"><a href="#d5e1223">(Suppressing) contributed actions</a></span></dt><dt><span class="sect2"><a href="#d5e1245">(Suppressing) service menu items</a></span></dt><dt><span class="sect2"><a href="#d5e1254">(Suppressing) service menus</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1259">How to use a generic repository</a></span></dt><dt><span class="sect1"><a href="#sec.CustomRepository">How to write a custom repository</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1307">Finding by Title</a></span></dt><dt><span class="sect2"><a href="#d5e1323">Finding by Pattern</a></span></dt><dt><span class="sect2"><a href="#d5e1345">Finding using the <code class="classname">Filter</code> API</a></sp
an></dt><dt><span class="sect2"><a href="#d5e1368">Finding using the <code class="classname">Query</code> API</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1412">Factories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.ValueTypes">10. Value Types</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1454">Built-in Value Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1458">JDK Types</a></span></dt><dt><span class="sect2"><a href="#d5e1536">Value formats</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1633">Custom Value Types</a></span></dt><dt><span class="sect1"><a href="#d5e1672">Third-party Value Types</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#prt.SupportingFeatures">II. Supporting Features</a></span></dt><dd><dl><dt><span class="chapter"><a href="#chp.Clock">11. Clock</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1703">Lazily Instantiated</a></span></dt><dt><sp
an class="sect1"><a href="#d5e1712">Possibly Replaceable</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.UserProfiles">12. Profiles</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1726">Profiles and Perspectives</a></span></dt><dt><span class="sect1"><a href="#d5e1749">Runtime and Viewer Support</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Fixtures">13. Fixtures and SwitchUser</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.HowToRegisterFixtures">How to register fixtures</a></span></dt><dt><span class="sect1"><a href="#d5e1780">How to write custom fixtures</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1786"><code class="classname">InstallableFixture</code> and
+ <code class="classname">FixtureType</code></a></span></dt><dt><span class="sect2"><a href="#d5e1806"><code class="classname">BaseFixture</code> and
+ <code class="classname">AbstractFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e1839"><code class="methodname">DateFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e1850"><code class="methodname">SwitchUserFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e1870"><code class="classname">LogonFixture</code></a></span></dt><dt><span class="sect2"><a href="#d5e1877"><code class="classname">UserProfileFixture</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chp.XmlSnapshots">14. XML Snapshots</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1907">Generating an XML Snapshot</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1911">Basic Usage</a></span></dt><dt><span class="sect2"><a href="#d5e1920">Including other Elements</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1936">Using the Fluent API</a></span></dt><dt><span class="sect1"><a href="#d5e1941">The
<code class="classname">SnapshottableWithInclusions</code>
+ interface</a></span></dt><dt><span class="sect1"><a href="#d5e1950">Generating an XSD schema</a></span></dt><dt><span class="sect1"><a href="#d5e1957">Hints and Tips</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#prt.ReferenceAppendices">III. Reference Appendices</a></span></dt><dd><dl><dt><span class="appendix"><a href="#d5e1969">A. Recognized Methods and Prefixes</a></span></dt><dt><span class="appendix"><a href="#d5e2241">B. Recognized Annotations</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e2248">@ActionOrder</a></span></dt><dt><span class="sect1"><a href="#d5e2267">@ActionSemantics</a></span></dt><dt><span class="sect1"><a href="#d5e2277">@AutoComplete</a></span></dt><dt><span class="sect1"><a href="#d5e2286">@Aggregated</a></span></dt><dt><span class="sect1"><a href="#d5e2294">@Bounded</a></span></dt><dt><span class="sect1"><a href="#sec.DebugAnnotation">@Debug</a></span></dt><dt><span class="sect1"><a href="#d5e2313">@Defaul
ted</a></span></dt><dt><span class="sect1"><a href="#d5e2323">@DescribedAs</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2331">Providing a description for an object</a></span></dt><dt><span class="sect2"><a href="#d5e2337">Providing a description for an object member</a></span></dt><dt><span class="sect2"><a href="#d5e2343">Providing a description for an action parameter</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e2349">@Disabled</a></span></dt><dt><span class="sect1"><a href="#d5e2418">@Encodable</a></span></dt><dt><span class="sect1"><a href="#d5e2428">@EqualByContent</a></span></dt><dt><span class="sect1"><a href="#d5e2437">@Executed</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2443">Forcing a method to be executed on the client</a></span></dt><dt><span class="sect2"><a href="#d5e2447">Forcing a method to be executed on the server</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.ExplorationAnnotation">@Explorati
on</a></span></dt><dt><span class="sect1"><a href="#d5e2462">@Facets</a></span></dt><dt><span class="sect1"><a href="#d5e2471">@FieldOrder</a></span></dt><dt><span class="sect1"><a href="#sec.HiddenAnnotation">@Hidden</a></span></dt><dt><span class="sect1"><a href="#d5e2555">@Idempotent (deprecated)</a></span></dt><dt><span class="sect1"><a href="#d5e2559">@Ignore (deprecated)</a></span></dt><dt><span class="sect1"><a href="#d5e2566">@Immutable</a></span></dt><dt><span class="sect1"><a href="#sec.MaskAnnotation">@Mask</a></span></dt><dt><span class="sect1"><a href="#sec.MaxLengthAnnotation">@MaxLength</a></span></dt><dt><span class="sect1"><a href="#sec.MemberGroupsAnnotation">@MemberGroups</a></span></dt><dt><span class="sect1"><a href="#sec.MemberOrderAnnotation">@MemberOrder</a></span></dt><dt><span class="sect1"><a href="#d5e2657">@MultiLine</a></span></dt><dt><span class="sect1"><a href="#d5e2688">@MustSatisfy</a></span></dt><dt><span class="sect1"><a href="#sec.NamedAn
notation">@Named</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2712">Specifying the name of an object</a></span></dt><dt><span class="sect2"><a href="#d5e2721">Specifying the name of a class member</a></span></dt><dt><span class="sect2"><a href="#d5e2730">Specifying the name for an action parameter</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.NotContributedAnnotation">@NotContributed</a></span></dt><dt><span class="sect1"><a href="#sec.NotInServiceMenuAnnotation">@NotInServiceMenu</a></span></dt><dt><span class="sect1"><a href="#not-persistable">@NotPersistable</a></span></dt><dt><span class="sect1"><a href="#d5e2781">@NotPersisted</a></span></dt><dt><span class="sect1"><a href="#d5e2789">@ObjectType</a></span></dt><dt><span class="sect1"><a href="#d5e2799">@Optional</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e2808">Making a property optional</a></span></dt><dt><span class="sect2"><a href="#d5e2817">Making an action parameter o
ptional</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e2822">@Paged</a></span></dt><dt><span class="sect1"><a href="#d5e2837">@Parseable</a></span></dt><dt><span class="sect1"><a href="#sec.PluralAnnotation">@Plural</a></span></dt><dt><span class="sect1"><a href="#d5e2857">@Programmatic</a></span></dt><dt><span class="sect1"><a href="#sec.PrototypeAnnotation">@Prototype</a></span></dt><dt><span class="sect1"><a href="#d5e2879">@QueryOnly (deprecated)</a></span></dt><dt><span class="sect1"><a href="#sec.RegExAnnotation">@RegEx</a></span></dt><dt><span class="sect1"><a href="#d5e2900">@Resolve</a></span></dt><dt><span class="sect1"><a href="#sec.TitleAnnotation">@Title</a></span></dt><dt><span class="sect1"><a href="#d5e2931">@TypeOf</a></span></dt><dt><span class="sect1"><a href="#d5e2939">@TypicalLength</a></span></dt><dt><span class="sect1"><a href="#sec.ValueAnnotation">@Value</a></span></dt><dt><span class="sect1"><a href="#d5e2965">@ViewModel</a></span></d
t></dl></dd><dt><span class="appendix"><a href="#apx.DomainObjectContainer">C. <code class="classname">DomainObjectContainer</code> interface</a></span></dt><dt><span class="appendix"><a href="#apx.SecurityClasses">D. Security Classes</a></span></dt><dt><span class="appendix"><a href="#apx.UtilityClasses">E. Utility Classes</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e3172">Title creation</a></span></dt><dt><span class="sect1"><a href="#d5e3179">Reason text creation (for disable and validate methods)</a></span></dt></dl></dd><dt><span class="appendix"><a href="#d5e3194">F. Events</a></span></dt><dt><span class="appendix"><a href="#d5e3205">G. Package Dependencies</a></span></dt></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>7.1. <a href="#d5e1063">Object lifecycle methods</a></dt><dt>A.1. <a href="#d5e1973">Recognized Method Prefixes</a></dt><dt>A.2. <a href="#d5e2186">Deprecated Method Prefixes</a></dt><dt>C.1. <a href="#
d5e2983">DomainObjectContainer methods (1 of 2)</a></dt><dt>C.2. <a href="#d5e3048">DomainObjectContainer methods (2 of 2)</a></dt></dl></div>
@@ -61,11 +59,8 @@
<p><span class="emphasis"><em>Apache Isis</em></span> is designed to allow programmers
rapidly develop domain-driven applications following the <a class="ulink" href="http://en.wikipedia.org/wiki/Naked_Objects" target="_top">Naked Objects</a>
- pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and runtimes/object stores.
- Apache Isis is hosted at the <a class="ulink" href="http://incubator.apache.org/isis" target="_top">Apache Foundation</a>, and is
- licensed under <a class="ulink" href="http://www.apache.org/licenses/LICENSE-2.0.html" target="_top">Apache Software
- License v2</a>.</p>
+ pattern. It is made up of a core plus a number of components for each of
+ the main APIs: objectstores, security, viewers and profilestores.</p>
<p>This guide is written for programmers looking to understand the
programming conventions, annotations and supporting utilities within the
@@ -73,1064 +68,332 @@
<span class="emphasis"><em>applib</em></span>), in order that the framework can correctly
pick up and render the business rules and logic encoded within their
domain objects.</p>
+
+ <p><span class="emphasis"><em>Apache Isis</em></span> is hosted at the <a class="ulink" href="http://incubator.apache.org/isis" target="_top">Apache Foundation</a>, and is
+ licensed under <a class="ulink" href="http://www.apache.org/licenses/LICENSE-2.0.html" target="_top">Apache Software
+ License v2</a>.</p>
</div>
- <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="d5e26"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d5e30">What's in this Guide</a></span></dt><dt><span class="sect1"><a href="#d5e40">This Guide vs the Core Documentation</a></span></dt><dt><span class="sect1"><a href="#d5e56">Where Next?</a></span></dt></dl></div>
+ <div class="part" title="Part I. Writing Domain Objects"><div class="titlepage"><div><div><h1 class="title"><a name="prt.WritingDomainObjects"></a>Part I. Writing Domain Objects</h1></div></div></div>
- <div class="abstract" title="Abstract"><div class="titlepage"></div>
- <p>What this guide contains, who it is for, and how the applib
- relates to other parts of the framework.</p>
- </div>
-
- <div class="sect1" title="What's in this Guide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e30"></a>What's in this Guide</h2></div></div></div>
-
-
- <p>This guide describes the set of conventions for writing domain
- objects, that are together known as the <span class="emphasis"><em>Apache Isis</em></span>
- Programming Model. It's important reading for developers who are looking
- to write domain-driven applications either for prototyping or deployment
- on <span class="emphasis"><em>Apache Isis</em></span>.</p>
-
- <p>More correctly, this guide actually documents the
- <span class="emphasis"><em>default</em></span> programming model, targetted for the Java
- programming language, and implemented by the
- <code class="classname">org.apache.isis.progmodels:dflt</code> module.
- <span class="emphasis"><em>Isis</em></span> is in fact capable of supporting different
- programming models, either for other JVM-based languages; for example
- the Groovy language is supported in the
- <code class="classname">org.apache.isis.progmodels:groovy</code> module. Those
- other programming models have their own documentation.</p>
- </div>
-
- <div class="sect1" title="This Guide vs the Core Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e40"></a>This Guide vs the Core Documentation</h2></div></div></div>
-
-
- <p>This guide assumes that you have at least the outline of a running
- <span class="emphasis"><em>Apache Isis</em></span> application, for example having run the
- quickstart archetype. Details of how to run the quickstart archetype can
- be found on the <span class="emphasis"><em>Isis</em></span> <a class="ulink" href="http://incubator.apache.org/isis" target="_top">website</a>.</p>
-
- <p>This guide has two main objectives:</p>
-
- <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
- <p>to describe the general approach for developing Isis
- applications solely by writing domain objects</p>
- </li><li class="listitem">
- <p>to describe the specifics of writing domain objects according
- to the conventions of the <span class="emphasis"><em>default</em></span> programming
- model.</p>
- </li></ul></div>
-
- <p>The core documentation, on the other hand, explains the wider
- landscape of what makes up an <span class="emphasis"><em>Isis</em></span> application,
- dealing with such matters as running the app with different components,
- eg viewers, security, programming models, profile stores and
- runtimes/object stores. Included within this is an explanation of how
- you can build your <span class="emphasis"><em>own</em></span> programming model (typically
- as a subset of the default programming model described here, but
- possibly with additional custom elements).</p>
- </div>
-
- <div class="sect1" title="Where Next?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e56"></a>Where Next?</h2></div></div></div>
-
-
- <p>This guide is in several parts. The first part is intended to
- explain, from a developers' perspective, what exactly <span class="emphasis"><em>Apache
- Isis</em></span> is. The second part has chapters that describe the
- specifics in the style of recipes/cookbooks, providing a "how-to" guide
- on developing domain objects. The third part provides details on other
- supporting features relevant to writing domain applications. The final
- part is a series of appendices that provide details of the programming
- model in reference form. You should find this more useful if you've used
- <span class="emphasis"><em>Isis</em></span> for a while and just need to check on a
- specific detail.</p>
- </div>
- </div>
-
- <div class="part" title="Part I. Understanding Apache Isis"><div class="titlepage"><div><div><h1 class="title"><a name="prt.UnderstandingApacheIsis"></a>Part I. Understanding Apache Isis</h1></div></div></div>
-
+ <div class="partintro" title="Writing Domain Objects"><div></div>
+ <p>The conventions of the programming model are best described as
+ 'intentional' - they convey an intention as to how domain objects, their
+ properties and behaviours, are to be made available to users. The
+ specific way in which those intentions are interpreted or implemented
+ will depend upon the framework, and/or the particular components or
+ options selected within that framework.</p>
- <div class="partintro" title="Understanding Apache Isis"><div></div>
- <p>The chapters in this part of the guide are intended to help you
- understand <span class="emphasis"><em>Apache Isis</em></span> from a developers'
- perspective:</p>
+ <p>To pick a single example, marking up a domain class with the
+ annotation <code class="code">@Bounded</code> is an indication that the class is
+ intended to have only a small number of instances and that the set does
+ not change very often - such as the class <code class="code">Country</code>. This is
+ an indication to a viewer, for example, that the whole set of instances
+ might be offered to the user in a convenient form such as a drop-down
+ list. The programming convention has <span class="emphasis"><em>not</em></span> been
+ defined as <code class="code">@DropDownList</code> because any equivalent mechanism
+ will suffice: a viewer might not support drop-down-lists but instead
+ might provide a capability to select from an <code class="code">@Bounded</code> class
+ by typing the initial letters of the desired instance.</p>
- <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
- <p>the principles and patterns that underpin
- <span class="emphasis"><em>Isis</em></span> (<a class="xref" href="#chp.PrinciplesAndPatterns" title="Chapter 2. Apache Isis and Naked Objects">Chapter 2, <i>Apache Isis and Naked Objects</i></a>)</p>
- </li><li class="listitem">
- <p>a development process to follow (<a class="xref" href="#chp.DevelopmentProcess" title="Chapter 3. A Development Process">Chapter 3, <i>A Development Process</i></a>)</p>
- </li></ul></div>
- <div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#chp.PrinciplesAndPatterns">2. Apache Isis and Naked Objects</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e84">Apache Isis implements the naked objects pattern... but what is
- that, exactly?</a></span></dt><dt><span class="sect1"><a href="#d5e91">What type of applications are best suited to Isis?</a></span></dt><dt><span class="sect1"><a href="#d5e99">And are there applications where the OO UIs generated by Isis
- are less suitable?</a></span></dt><dt><span class="sect1"><a href="#d5e112">What is the typical development process life cycle for
- applications built with Isis, and how does it compare to traditional
- application development process?</a></span></dt><dt><span class="sect1"><a href="#d5e144">What are the limitations of Apache Isis framework?</a></span></dt><dt><span class="sect1"><a href="#d5e172">How extensive is the application security support provided by
- Isis?</a></span></dt><dt><span class="sect1"><a href="#d5e187">How does an Isis applications manage the custom logic in terms
- of business rules, workflow and other business logic that developers
- have to manually implement outside the generated code?</a></span></dt><dt><span class="sect1"><a href="#d5e192">How does Isis support SOA-based applications, eg where an
- enterprise service component is consumed by several different
- applications and other clients?</a></span></dt><dt><span class="sect1"><a href="#d5e208">Most enterprise applications need to reuse the domain and
- service layer classes between several different applications. How does
- Apache Isis address this?</a></span></dt><dt><span class="sect1"><a href="#d5e225">What is the future road map of the project?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.DevelopmentProcess">3. A Development Process</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.ApplicationArchetypes">Run the Quickstart Archetype</a></span></dt><dt><span class="sect1"><a href="#d5e250">Programming Model</a></span></dt><dt><span class="sect1"><a href="#d5e258">Fixtures and Prototyping</a></span></dt><dt><span class="sect1"><a href="#sec.Viewers">Viewers</a></span></dt><dt><span class="sect1"><a href="#sec.AgileTesting">Agile Testing</a></span></dt><dd><dl><dt><span class="sect2"><a href="#sec.BddTesting">Story (BDD) Testing</a></span></dt><dt><span class="sect2"><a href="#sec.UnitTesting">Unit Testing</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e322">A Domain Library</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e331">Do
main Services</a></span></dt><dt><span class="sect2"><a href="#d5e343">Domain Values</a></span></dt><dt><span class="sect2"><a href="#d5e355">Domain Entities</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DeployingAnIsisApplication">Deploying an Isis Application</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e365">Persistence (the Default Runtime / Object Store)</a></span></dt><dt><span class="sect2"><a href="#d5e398">Authentication and Authorization</a></span></dt></dl></dd></dl></dd></dl></div></div>
-
- <div class="chapter" title="Chapter 2. Apache Isis and Naked Objects"><div class="titlepage"><div><div><h2 class="title"><a name="chp.PrinciplesAndPatterns"></a>Chapter 2. Apache Isis and Naked Objects</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d5e84">Apache Isis implements the naked objects pattern... but what is
- that, exactly?</a></span></dt><dt><span class="sect1"><a href="#d5e91">What type of applications are best suited to Isis?</a></span></dt><dt><span class="sect1"><a href="#d5e99">And are there applications where the OO UIs generated by Isis
- are less suitable?</a></span></dt><dt><span class="sect1"><a href="#d5e112">What is the typical development process life cycle for
- applications built with Isis, and how does it compare to traditional
- application development process?</a></span></dt><dt><span class="sect1"><a href="#d5e144">What are the limitations of Apache Isis framework?</a></span></dt><dt><span class="sect1"><a href="#d5e172">How extensive is the application security support provided by
- Isis?</a></span></dt><dt><span class="sect1"><a href="#d5e187">How does an Isis applications manage the custom logic in terms
- of business rules, workflow and other business logic that developers
- have to manually implement outside the generated code?</a></span></dt><dt><span class="sect1"><a href="#d5e192">How does Isis support SOA-based applications, eg where an
- enterprise service component is consumed by several different
- applications and other clients?</a></span></dt><dt><span class="sect1"><a href="#d5e208">Most enterprise applications need to reuse the domain and
- service layer classes between several different applications. How does
- Apache Isis address this?</a></span></dt><dt><span class="sect1"><a href="#d5e225">What is the future road map of the project?</a></span></dt></dl></div>
+ <p>This part of the guide is a set of chapters that provides how-to's
+ for writing domain objects, by which we mean domain entities, value
+ types, services and repositories/factories.</p>
+ <div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#chp.Objects">1. How to write a basic Domain Entity or Service</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e44">How to have a domain entity be a POJO (not inherit from
+ framework superclasses)</a></span></dt><dt><span class="sect1"><a href="#sec.AbstractService">How to have a domain service be a POJO (not inherit from
+ framework superclasses)</a></span></dt><dt><span class="sect1"><a href="#d5e71">How to add a property to a domain entity</a></span></dt><dt><span class="sect1"><a href="#d5e91">How to add a collection to a domain entity</a></span></dt><dt><span class="sect1"><a href="#d5e119">How to add an action to a domain entity or service</a></span></dt><dt><span class="sect1"><a href="#d5e150">How to specify a title for a domain
+ entity</a></span></dt><dt><span class="sect1"><a href="#sec.HowToSpecifyTheIconForAnObjectsClass">How to specify the icon for a domain
+ entity</a></span></dt><dt><span class="sect1"><a href="#sec.MemberOrderForProperties">How to specify the order in which properties or collections are
+ displayed</a></span></dt><dt><span class="sect1"><a href="#d5e200">How to specify the order in which actions appear on the
+ menu</a></span></dt><dt><span class="sect1"><a href="#d5e209">How to make a property optional (when saving an object)</a></span></dt><dt><span class="sect1"><a href="#d5e214">How to make an action parameter optional</a></span></dt><dt><span class="sect1"><a href="#sec.SizeProperties">How to specify the size of <code class="classname">String</code>
+ properties</a></span></dt><dt><span class="sect1"><a href="#d5e236">How to specify the size of <code class="classname">String</code> action
+ parameters</a></span></dt><dt><span class="sect1"><a href="#sec.ActionParameterNames">How to specify names and/or descriptions for an action
+ parameter</a></span></dt><dt><span class="sect1"><a href="#d5e266">How to inject services into a domain entity or other
+ service</a></span></dt><dt><span class="sect1"><a href="#sec.HowToCreateAnObject">How to create or delete objects within your code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.Properties">2. How to add business rules</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.HiddenProperty">How to hide a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e350">Hiding a property always</a></span></dt><dt><span class="sect2"><a href="#d5e356">Hiding a property based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e367">Hiding a property under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e378">Hiding a property for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.HiddenCollection">How to hide a collection</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e388">Hiding a collection permanently</a></span></dt><dt><span class="sect2"><a href="#d5e394">Hiding a collection based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e405">Hiding a collection under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e416">Hiding a collection for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.HiddenActions">How to hide an action</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e426">Hiding an action permanently</a></span></dt><dt><span class="sect2"><a href="#d5e433">Hiding an action based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e444">Hiding an action under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e455">Hiding an action for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.Entity.Hidden">How to specify that none of an object's members is
+ visible</a></span></dt><dt><span class="sect1"><a href="#sec.DisabledProperty">How to prevent a property from being modified</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e474">Disabling a property permanently</a></span></dt><dt><span class="sect2"><a href="#d5e481">Disabling a property based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e492">Disabling a property under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e505">Disabling a property for certain users/roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledCollection">How to prevent a collection from being modified</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e516">Disabling a collection permanently</a></span></dt><dt><span class="sect2"><a href="#d5e525">Disabling a collection based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e536">Disabling a collection under certain conditions</a></span></dt><dt><span class="sect2"><a href="#d5e545">Disabling a collection for specific users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DisabledAction">How to prevent an action from being invoked</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e556">Disabling an action permanently</a></span></dt><dt><span class="sect2"><a href="#d5e560">Disabling an action based on the persistence state of the
+ object</a></span></dt><dt><span class="sect2"><a href="#d5e572">Based on the state of the object</a></span></dt><dt><span class="sect2"><a href="#d5e584">Disabling an action for certain users or roles</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.Entity.Disabled">How to specify that none of an object's members can be
+ modified/invoked</a></span></dt><dt><span class="sect1"><a href="#sec.Immutable">How to specify that an object is
+ immutable (that none of its members can ever be modified)</a></span></dt><dt><span class="sect1"><a href="#d5e614">How to validate user input for a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e616">Declarative validation</a></span></dt><dt><span class="sect2"><a href="#d5e631">Imperative validation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e644">How to validate an object being added or removed from a
+ collection</a></span></dt><dt><span class="sect1"><a href="#d5e659">How to validate an action parameter argument</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e661">Declarative validation</a></span></dt><dt><span class="sect2"><a href="#d5e676">Imperative validation</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.MustSpecify">How to validate declaratively using @MustSatisfy</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e722">3. How to provide drop-downs and default values</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e728">How to specify a set of choices for a property</a></span></dt><dt><span class="sect1"><a href="#d5e745">How to specify a set of choices for an action parameter</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e751">Per parameter syntax (preferred)</a></span></dt><dt><span class="sect2"><a href="#d5e759">All parameters syntax</a></span></dt></dl></dd><dt><span class="sect1"><a href=
"#sec.Bounded">How to specify that a class of objects has a limited number of
+ instances</a></span></dt><dt><span class="sect1"><a href="#d5e779">How to find an entity (for an action parameter or property)
+ using auto-complete</a></span></dt><dt><span class="sect1"><a href="#d5e791">How to specify default values for an action parameter</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e795">Per-parameter syntax (preferred)</a></span></dt><dt><span class="sect2"><a href="#d5e802">All parameters syntax</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#d5e810">4. How to derive properties and collections, and other
+ side-effects</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.DerivedProperty">How to make a derived property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e818">Read-only</a></span></dt><dt><span class="sect2"><a href="#d5e825">Read-write</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.DerivedCollection">How to make a derived collection</a></span></dt><dt><span class="sect1"><a href="#d5e849">How to inline the results of a query-only repository
+ action</a></span></dt><dt><span class="sect1"><a href="#sec.ModifyAndClear">How to trigger other behaviour when a property is
+ changed</a></span></dt><dt><span class="sect1"><a href="#sec.AddToRemoveFrom">How to trigger other behaviour when an object is added or
+ removed</a></span></dt><dt><span class="sect1"><a href="#sec.MutualRegistrationPattern">How to set up and maintain bidirectional relationships</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e919">5. How to provide additional UI hints</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e927">How to specify a name and/or description for an
+ object</a></span></dt><dt><span class="sect1"><a href="#d5e939">How to specify a name and/or description for a property</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e941">Specifying the name for a property</a></span></dt><dt><span class="sect2"><a href="#d5e947">Specifying a description for a property</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e953">How to specify a name and/or description for a
+ collection</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e955">Specifying the name for a collection</a></span></dt><dt><span class="sect2"><a href="#d5e961">Specifying a description for a collection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e967">How to specify names and/or description for an action</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e969">Specifying the name for an action</a></span></dt><dt><span class="sect2"><a href="#d5e975">Specifying a description for a collection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e981">How to specify the icon for an individual object's
+ state</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e992">6. How to deal with errors</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.passMessagesAndErrors">How to pass a messages and errors back to the user</a></span></dt><dt><span class="sect1"><a href="#d5e1017">How to deal with an unexpected error</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e1024">7. How to handle entity persistence lifecycle</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.DefaultPropertyValue">How to set up the initial value of a property
+ programmatically</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1033">By each property's default values</a></span></dt><dt><span class="sect2"><a href="#d5e1042">By the <code class="methodname">created()</code> lifecycle
+ method</a></span></dt><dt><span class="sect2"><a href="#d5e1049">Programmatically, by the creator</a></span></dt></dl></dd><dt><span class="sect1"><a href="#sec.LifecycleMethods">How to insert behaviour into the object life cycle</a></span></dt><dt><span class="sect1"><a href="#d5e1114">How to ensure object is in valid state</a></span></dt><dt><span class="sect1"><a href="#d5e1133">How to specify that an object should not be
+ persisted</a></span></dt><dt><span class="sect1"><a href="#sec.ResolveAndObjectChanged">How to perform lazy loading (generally done
+ automatically)</a></span></dt><dt><span class="sect1"><a href="#d5e1150">How to perform dirty object tracking (generally done
+ automatically)</a></span></dt></dl></dd><dt><span class="chapter"><a href="#d5e1159">8. How to handle security concerns</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.BusinessRulesForCertainUsersOrRoles">Hiding, disabling or validating for specific users or
+ roles</a></span></dt><dt><span class="sect1"><a href="#d5e1180">How to use Isis' authorization manager</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.DomainServices">9. Domain Services, Repositories and Factories</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sec.Services">How to register domain services, repositories and
+ factories</a></span></dt><dt><span class="sect1"><a href="#d5e1208">How to write a typical domain service</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1215">The <code class="methodname">getId()</code> method</a></span></dt><dt><span class="sect2"><a href="#d5e1223">(Suppressing) contributed actions</a></span></dt><dt><span class="sect2"><a href="#d5e1245">(Suppressing) service menu items</a></span></dt><dt><span class="sect2"><a href="#d5e1254">(Suppressing) service menus</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1259">How to use a generic repository</a></span></dt><dt><span class="sect1"><a href="#sec.CustomRepository">How to write a custom repository</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1307">Finding by Title</a></span></dt><dt><span class="sect2"><a href="#d5e1323">Finding by Pattern</a></span></dt><dt><span class="sect2"><a href="#d5e1345">Finding using the <code class="classname">Filter</code> API</a></sp
an></dt><dt><span class="sect2"><a href="#d5e1368">Finding using the <code class="classname">Query</code> API</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1412">Factories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chp.ValueTypes">10. Value Types</a></span></dt><dd><dl><dt><span class="sect1"><a href="#d5e1454">Built-in Value Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d5e1458">JDK Types</a></span></dt><dt><span class="sect2"><a href="#d5e1536">Value formats</a></span></dt></dl></dd><dt><span class="sect1"><a href="#d5e1633">Custom Value Types</a></span></dt><dt><span class="sect1"><a href="#d5e1672">Third-party Value Types</a></span></dt></dl></dd></dl></div></div>
+
+ <div class="chapter" title="Chapter 1. How to write a basic Domain Entity or Service"><div class="titlepage"><div><div><h2 class="title"><a name="chp.Objects"></a>Chapter 1. How to write a basic Domain Entity or Service</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d5e44">How to have a domain entity be a POJO (not inherit from
+ framework superclasses)</a></span></dt><dt><span class="sect1"><a href="#sec.AbstractService">How to have a domain service be a POJO (not inherit from
+ framework superclasses)</a></span></dt><dt><span class="sect1"><a href="#d5e71">How to add a property to a domain entity</a></span></dt><dt><span class="sect1"><a href="#d5e91">How to add a collection to a domain entity</a></span></dt><dt><span class="sect1"><a href="#d5e119">How to add an action to a domain entity or service</a></span></dt><dt><span class="sect1"><a href="#d5e150">How to specify a title for a domain
+ entity</a></span></dt><dt><span class="sect1"><a href="#sec.HowToSpecifyTheIconForAnObjectsClass">How to specify the icon for a domain
+ entity</a></span></dt><dt><span class="sect1"><a href="#sec.MemberOrderForProperties">How to specify the order in which properties or collections are
+ displayed</a></span></dt><dt><span class="sect1"><a href="#d5e200">How to specify the order in which actions appear on the
+ menu</a></span></dt><dt><span class="sect1"><a href="#d5e209">How to make a property optional (when saving an object)</a></span></dt><dt><span class="sect1"><a href="#d5e214">How to make an action parameter optional</a></span></dt><dt><span class="sect1"><a href="#sec.SizeProperties">How to specify the size of <code class="classname">String</code>
+ properties</a></span></dt><dt><span class="sect1"><a href="#d5e236">How to specify the size of <code class="classname">String</code> action
+ parameters</a></span></dt><dt><span class="sect1"><a href="#sec.ActionParameterNames">How to specify names and/or descriptions for an action
+ parameter</a></span></dt><dt><span class="sect1"><a href="#d5e266">How to inject services into a domain entity or other
+ service</a></span></dt><dt><span class="sect1"><a href="#sec.HowToCreateAnObject">How to create or delete objects within your code</a></span></dt></dl></div>
<div class="abstract" title="Abstract"><div class="titlepage"></div>
- <p>Understanding Apache Isis and the naked objects pattern by way
- of a series of questions and answers.</p>
- </div>
-
- <p>The headline feature that distinguishes <span class="emphasis"><em>Apache
- Isis</em></span> from other frameworks is its support for the naked
- objects pattern - the ability to generate a user interface (at runtime)
- directly from the domain model. However, there's much more to
- <span class="emphasis"><em>Apache Isis</em></span> than this.</p>
-
- <p>This chapter introduces the <span class="emphasis"><em>Apache Isis</em></span> and
- the naked objects pattern by way of a series of questions and answers.
- It is adapted from an <a class="ulink" href="http://www.infoq.com/articles/haywood-ddd-no" target="_top">interview originally
- published on InfoQ</a>.</p>
-
- <div class="sect1" title="Apache Isis implements the naked objects pattern... but what is that, exactly?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e84"></a>Apache Isis implements the naked objects pattern... but what is
- that, exactly?</h2></div></div></div>
-
-
- <p>Naked objects is an architectural pattern where the idea is to
- automatically expose a domain model objects directly within a
- object-oriented user interface... not just their state (properties and
- collections) but also their behaviour (what we call actions). You can
- think of it as analogous to an <acronym class="acronym">ORM</acronym> such as <a class="ulink" href="http://hibernate.org" target="_top">Hibernate</a>; but whereas an
- <acronym class="acronym">ORM</acronym> reflects the domain model into the persistence
- layer, naked objects reflects the domain model into the presentation
- layer.</p>
-
- <p>Naked Objects (capitals) was a Java framework that implemented
- the naked objects (lower case) pattern. Since then, we've taken the
- original framework, along with a number of sister projects developed
- by the community, into the Apache Incubator. So, what was originally
- "Naked Objects" is now Apache Isis.</p>
- </div>
-
- <div class="sect1" title="What type of applications are best suited to Isis?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e91"></a>What type of applications are best suited to Isis?</h2></div></div></div>
-
-
- <p>The naked objects pattern requires that your primary
- consideration is in building an object-oriented domain model, so it's
- most suitable for enterprise applications that have complex business
- rules where there's a desire to represented them within such a domain
- model. The idea - at least during the initial stages - is to build up
- a domain model quickly, and to get feedback from the domain experts by
- exploiting the framework's ability to expose that directly domain
- model within the user interface. A picture tells a thousand
- words.</p>
-
- <p>Apache Isis "sweet spot" are those applications that are used
- internally within the organization, by experienced users who are
- comfortable with the entities within the domain model, and just need
- an application that imposes as few constraints as possible on how it
- is used. These are sometimes called <span class="emphasis"><em>sovereign
- applications</em></span>. If you're a developer then your
- <acronym class="acronym">IDE</acronym> is probably the sovereign application you use
- the most, and how often did you use any of its wizards? And if you use
- telephone banking then you'll also know how frustrating a sovereign
- application can be that is too invasive in dictating the workflow...
- that poor person on the other end asks making apologies while she goes
- exits from one screen and then goes into another to check some detail
- on a bank account. The generic <acronym class="acronym">OO</acronym>
- <acronym class="acronym">UI</acronym>s generated by naked objects impose no such
- restrictions, and so are ideal for this sort of application.</p>
- </div>
-
- <div class="sect1" title="And are there applications where the OO UIs generated by Isis are less suitable?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e99"></a>And are there applications where the OO UIs generated by Isis
- are less suitable?</h2></div></div></div>
-
-
- <p>The opposite of a sovereign application (above) is sometimes
- called a <span class="emphasis"><em>transient application</em></span>. These are ones
- used only occasionally or by inexperienced users, typically outside
- the organization (ie your customers), who don't know or care to know
- the domain model, and just want to be led through the system to
- accomplish some well-defined goal. A good example here is a check-in
- kiosk at an airport... you just want to get on the plane, and be given
- the opportunity to choose your seat. But you likely won't care which
- plane, or even plane type, nor who the pilot is; these are unimportant
- details.</p>
-
- <p>For this sort of application a generic <acronym class="acronym">OO</acronym>
- <acronym class="acronym">UI</acronym> that exposes lots of the domain is clearly not
- appropriate. Instead, we want an application that exposes view models
- rather than entities, and where the <acronym class="acronym">UI</acronym> can be
- customized. The view model object is responsible for managing the
- workflow for the user story, exposing just the subset of the domain
- that is relevant, and hiding the rest of the domain. We find that
- these view models can be layered on top of the entities once those
- entities are understood.</p>
-
- <p>Using view model objects is necessary but probably not
- sufficient for transient applications; we also usually need to
- customize the <acronym class="acronym">UI</acronym>. <span class="emphasis"><em>Apache Isis</em></span>
- has two viewers that allow the UI to be customized, one that provides
- a set of taglibs, and one that provides a set of <a class="ulink" href="http://wicket.apache.org" target="_top">Apache Wicket</a>
- components.</p>
-
- <p>Putting both of these techniques together (custom view models
- and views) means that Apache Isis is suitable for transient
- applications as well as sovereign applications. However, the former
- will necessarily take more work as opposed to the latter.</p>
- </div>
-
- <div class="sect1" title="What is the typical development process life cycle for applications built with Isis, and how does it compare to traditional application development process?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d5e112"></a>What is the typical development process life cycle for
- applications built with Isis, and how does it compare to traditional
- application development process?</h2></div></div></div>
-
-
- <p>The main difference you're likely to encounter is the emphasis
- on developing the domain model at the same time as identifying and
- prioritizing user stories, what those practicing domain driven design
- call a "ubiquitous language" for the team.</p>
-
- <p>So, rather than let the developers in the team "discover" the
- domain model as part of story implementation, we'd expect that the
- domain experts/business analysts have already identified some of the
- main domain concepts through prototyping or spikes, and these can be
- used to help communicate the stories to the developers during the
- planning game. Not every business analyst is going to feel comfortable
- working with an <acronym class="acronym">IDE</acronym>, but it works well to pair with
- a developer. Because an Apache Isis application can be runs just from
- domain classes, it's possible to develop the app very very quickly.
- We've found a good technique is to run workshops with the business
- analyst facilitating the meeting with the domain experts, and the
- developer acting as "code monkey" to rapidly convert the ideas into an
- app. Obviously the code isn't production quality, but it allows the
- team as a whole to go very quickly and experiment with different
- representations of the model.</p>
-
- <p>Another alternative is to go a little more slowly, and have the
- analyst and developer pairing to write production code. The analyst
- still focuses on identifying and naming the domain concepts and their
- relationships, while the developer's role (as well as learning about
- the domain) is to ensure that there's enough rigour and tests around
- the code that's been written while this is being done. Of course, both
- approaches to pairing can be used, sometimes spiking ideas, sometimes
- going straight to writing tested code.</p>
-
- <p>Of course, while the naked objects pattern means that no
- <acronym class="acronym">UI</acronym> code needs to be written in order to elicit
- feedback, there do still need to be objects in the app for the domain
- expert to view. Apache Isis has a pluggable runtime/persistence layer,
- and for prototyping and most of development we recommend using the
[... 5583 lines stripped ...]