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 2010/12/11 09:33:53 UTC
svn commit: r1044582 -
/incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml
Author: danhaywood
Date: Sat Dec 11 08:33:53 2010
New Revision: 1044582
URL: http://svn.apache.org/viewvc?rev=1044582&view=rev
Log:
tidying up the applib documentation
Modified:
incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml
Modified: incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml?rev=1044582&r1=1044581&r2=1044582&view=diff
==============================================================================
--- incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml (original)
+++ incubator/isis/trunk/applib/src/docbkx/guide/isis-applib.xml Sat Dec 11 08:33:53 2010
@@ -39,12 +39,6 @@
<surname>Matthews</surname>
</author>
-
- <author>
- <firstname>Kevin</firstname>
-
- <surname>Meyer</surname>
- </author>
</authorgroup>
<legalnotice>
@@ -81,24 +75,60 @@
<!-- main content -->
- <part>
- <title>The Default Programming Model</title>
+ <chapter>
+ <title>Introduction</title>
- <chapter>
- <title>Developing domain objects - a how-to guide</title>
+ <abstract>
+ <para>What this guide contains, who it is for, and how the applib
+ relates to other parts of the framework.</para>
+ </abstract>
+
+ <sect1>
+ <title>What's in this Guide</title>
+
+ <para>This guide describes the set of conventions for writing domain
+ objects, that are together known as the <emphasis>Apache Isis</emphasis>
+ Programming Model. It's important reading for developers who are looking
+ to write domain-driven applications either for prototyping or deployment
+ on <emphasis>Apache Isis</emphasis>.</para>
+
+ <para>More correctly, this guide actually documents the
+ <emphasis>default</emphasis> programming model, targetted for the Java
+ programming language, and implemented by the
+ <classname>org.apache.isis.defaults:progmodel</classname> module.
+ <emphasis>Isis</emphasis> is in fact capable of supporting different
+ programming models, either for other JVM-based languages; for example
+ the Groovy language is supported in the
+ <classname>org.apache.isis.alternatives.progmodel:groovy</classname>
+ module.</para>
+ </sect1>
+
+ <sect1>
+ <title>This Guide vs the Core Documentation</title>
+
+ <para>This guide assumes that you have at least the outline of a running
+ <emphasis>Apache Isis</emphasis> application, for example having run the
+ quickstart archetype. If you haven't done this, then please consult the
+ core documentation to learn how.</para>
+
+ <para>You should also note that the core documentation also explains the
+ wider landscape of what makes up an <emphasis>Isis</emphasis>
+ application, dealing with such matters as running the app with different
+ components, eg viewers or object stores.</para>
+
+ <para>Indeed, it is also possible for developers to build their own
+ programming model, either as a subset of the default programming model
+ described here, and possibly with additional custom elements. See the
+ core documentation for details on how to write your own programming
+ model.</para>
+
+ <para>However, everything related to the specifics of writing a domain
+ object with the <emphasis>default</emphasis> programming model is
+ here.</para>
+ </sect1>
- <para>This section defines a set of conventions for writing domain
- objects, that are together known as the '[[NAME]] (Java) Programming
- Model'.</para>
-
- <para>Following these conventions does not tie your domain objects to
- the [[NAME]] Framework or any other framework: the resulting domain
- objects may be run within any framework or platform that supports POJOs
- (Plain Old Java Objects). A few of the conventions do make use of
- Interfaces or Annotations that are necessarily defined somewhere - in
- this case they are in the [[NAME]] AppLib. However, the AppLib is not
- itself dependent upon the [[NAME]] Framework (and in theory another
- framework implementation could support the same applib).</para>
+ <sect1>
+ <title>Principles</title>
<para>The conventions of the programming model are best described as
'intentional' - they convey an intention as to how domain objects, their
@@ -118,8 +148,43 @@
might not support drop-down-lists - but it might provide a capability to
select from an <code>@Bounded</code> class by typing the initial letters
of the desired instance.</para>
+ </sect1>
- <sect1>
+ <sect1>
+ <title>Where Next?</title>
+
+ <para>This guide itself is in two parts. The first is a set of chapters
+ is written in the style of recipes/cookbooks, providing a "how-to" guide
+ on developing domain objects. This is good reading if you are just
+ starting out. The second 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 Isis for a while and just need to check on a
+ specific detail.</para>
+ </sect1>
+ </chapter>
+
+ <part>
+ <title>AppLib Recipes</title>
+
+ <partintro>
+ <para>This part of the guide is a set of chapters that provides recipes
+ / how-to's for the object, for services, for fixtures and
+ so-forth.</para>
+ </partintro>
+
+ <chapter>
+ <title>Object Recipes</title>
+
+ <abstract>
+ <para>How-to's relating to the object itself</para>
+ </abstract>
+
+ <para>This chapter contains how-to's for programming conventions that
+ apply to the object itself: object-level specifications (<xref
+ linkend="sec.ObjectLevelSpecifications" />) and the object lifecycle
+ (<xref linkend="sec.ObjectLifecycle" />).</para>
+
+ <sect1 id="sec.ObjectLevelSpecifications">
<title>Object-level specifications</title>
<para>The first set of conventions are concerned with the capabilities
@@ -273,7 +338,7 @@
</sect2>
</sect1>
- <sect1>
+ <sect1 id="sec.ObjectLifecycle">
<title>The object lifecycle</title>
<para>These conventions are concerned with the creation, retrieval,
@@ -319,10 +384,11 @@
<para><literal moreinfo="none">void remove(Object object)</literal>
deletes a persistent object from the object store.</para>
- <para>Any framework that recognises the [[NAME]] Programming Model
- will provide an implementation of <code>DomainObjectContainer</code>
- and will take responsibility to inject a reference to that Container
- into any domain object that needs it.</para>
+ <para>Any framework that recognises the Apache Isis Programming
+ Model will provide an implementation of
+ <code>DomainObjectContainer</code> and will take responsibility to
+ inject a reference to that Container into any domain object that
+ needs it.</para>
<para>A domain object specifies that it needs to have a reference to
the Container injected into by including the following code:</para>
@@ -438,9 +504,42 @@
compatibility <methodname>deleted()</methodname> is also
supported).</para>
</sect2>
+
+ <sect2 id="sec.ResolveAndObjectChanged">
+ <title>The resolve() and objectChanged() methods</title>
+
+ <para>In earlier versions of the framework it was necessary to call
+ the inherited <methodname>resolve()</methodname> method within every
+ property or collection's getter, and
+ <methodname>objectChanged()</methodname> within every property's
+ setter and every collection's addTo or removeFrom.</para>
+
+ <para>These methods still exist in
+ <classname>AbstractDomainObject</classname>, but no longer need to
+ be called explicitly. Instead Apache Isis uses bytecode enhancement
+ (using either cglib or javassist) to automatically call these
+ methods. This bytecode enhancement can be disabled in
+ <filename>isis.properties</filename> file; if it is then the methods
+ must be called manually.</para>
+ </sect2>
</sect1>
+ </chapter>
- <sect1>
+ <chapter>
+ <title>Object Member Recipes</title>
+
+ <abstract>
+ <para>How-to's relating to an object's class members.</para>
+ </abstract>
+
+ <para>This chapter contains how-to's for programming conventions that
+ apply to an object's class members: properties (<xref
+ linkend="sec.Properties" />), collections (<xref
+ linkend="sec.Collections" />) and actions (<xref
+ linkend="sec.Actions" />). It also covers an alternative mechanism for
+ specifying business rules (<xref linkend="sec.MustSpecify" />).</para>
+
+ <sect1 id="sec.Properties">
<title>Properties</title>
<para>The following conventions are concerned with specifying the
@@ -845,7 +944,219 @@ public void modifyAmount(int amount) {
</sect2>
</sect1>
- <sect1>
+ <sect1 id="sec.Collections">
+ <title>Collections</title>
+
+ <para>A collection is a list of references to several entity objects
+ that have a common type.</para>
+
+ <sect2>
+ <title>How to add a collection to an object</title>
+
+ <para>A collection is recognized via an accessor/mutator method pair
+ (<code>get</code> and set) for any type of collection provided by
+ the programming language. The syntax is:</para>
+
+ <para><programlisting>public <collection type> get<CollectionName>()
+
+private void set<CollectionName>(<collection type> param)</programlisting></para>
+
+ <para>It is recommended that the collections be specified using
+ generics (for example: <literal
+ moreinfo="none">List<Customer></literal> ). That way the
+ framework will be able to display the collection based on that type
+ definition. (Generics are also required by some persistence
+ mechanisms). For example the viewer might display the collection as
+ a table, with the columns defined by the visible properties of that
+ type. The viewer will then automatically prevent the user from
+ adding objects not of that type. If generics are not used then the
+ type may be inferred from the <literal
+ moreinfo="none">addTo</literal> / <literal
+ moreinfo="none">removeFrom</literal> methods, if specified (see
+ below).</para>
+
+ <para>For example:</para>
+
+ <programlisting format="linespecific">public class Employee { ... }
+
+public class Department {
+ private List<Employee> employees = new ArrayList<Employee>();
+ public List <Employee> getEmployees() {
+ return employees;
+ }
+ private void setEmployees(List<Employee> employees) {
+ this.employees = employees;
+ }
+ ...
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>How to trigger other behaviour when an object is added or
+ removed</title>
+
+ <para>A collection may have a corresponding <literal
+ moreinfo="none">addTo</literal> and/or <literal
+ moreinfo="none">removeFrom</literal> method. This is equivalent to
+ the <literal moreinfo="none">modify</literal> and <literal
+ moreinfo="none">clear</literal> methods for properties. The syntax
+ is:</para>
+
+ <para><programlisting>public void addTo<CollectionName>(<entity type> param)
+
+public void removeFrom<CollectionName>(<entity type> param)</programlisting></para>
+
+ <para>where <literal moreinfo="none"><entity type></literal>
+ is the same type as the generic collection type. For example:</para>
+
+ <programlisting format="linespecific">public class Employee { ... }
+
+public class Department {
+ private List<Employee> employees = new ArrayList<Employee>();
+ public List <Employee> getEmployees() {
+ return employees;
+ }
+ private void setEmployees(List<Employee> employees) {
+ this.employees = employees;
+ }
+ public void addToEmployees(Employee employee) {
+ employees.add(employee);
+ }
+ public void removeFromEmployees(Employee employee) {
+ employees.remove(employee);
+ }
+
+ ...
+}</programlisting>
+
+ <para>The addTo / removeFrom and modify / clear methods are
+ particularly useful in setting up bidirectional relationships using
+ the 'mutual registration pattern'; for a write-up of this pattern,
+ see <ulink
+ url="???">http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf</ulink>.</para>
+ </sect2>
+
+ <sect2>
+ <title>How to prevent the user from modifying a collection</title>
+
+ <para>Preventing the user from adding to or removing from a
+ collection is known as 'disabling' the collection.</para>
+
+ <sect3>
+ <title>Disabling a collection permanently</title>
+
+ <para>Use the <literal moreinfo="none">@Disabled</literal>
+ annotation.</para>
+ </sect3>
+
+ <sect3>
+ <title>Disabling a collection under certain conditions</title>
+
+ <para>A <literal moreinfo="none">disable</literal> method can be
+ used to disable a particular instance's collection under certain
+ conditions: The syntax is:</para>
+
+ <para><literal moreinfo="none">public String
+ disable<CollectionName>()</literal> For example:</para>
+
+ <programlisting format="linespecific">public class Department {
+ public List<Employee> getEmployees() { ... }
+ public void addToEmployees(Employee employee) { ... }
+ public void removeFromEmployees(Employee employee) { ... }
+ public void disableEmployees() {
+ return isClosed()? "This department is closed" : null;
+ }
+}</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Disabling a collection for specific users or roles</title>
+
+ <para>See Properties: Disabling a property for specific users or
+ roles'. The same technique can be applied to collections, with the
+ same caveats applying.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>How to validate an object to be added or removed</title>
+
+ <para>A <literal moreinfo="none">validate</literal> method is used
+ to check that an object to be added or removed from a collection is
+ valid. A non-null return <code>String</code> indicates the reason
+ why the object cannot be added/removed, and the viewing mechanism
+ will display this to the user. The syntax is:</para>
+
+ <para><programlisting>public String validateAddTo<CollectionName>(<property type> param)
+
+public String validateRemoveFrom<CollectionName>(<property type> param)</programlisting></para>
+
+ <para>For example:</para>
+
+ <programlisting format="linespecific">public class Department {
+ private List<Employee> employees = new ArrayList<Employee>();
+ public List<Employee> getEmployees() { ... }
+ private void setEmployees(List<Employee> employees) { ... }
+ public String validateAddToEmployee(Employee employee) {
+ return employee.isRetired()?
+ "Cannot add retired employees to department"
+ :null;
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>How to control the order in which collections are
+ displayed</title>
+
+ <para>Use the <literal moreinfo="none">@MemberOrder</literal>
+ annotation.</para>
+ </sect2>
+
+ <sect2>
+ <title>How to specify a name and/or description for a
+ collection</title>
+
+ <para>Use the <literal moreinfo="none">@Named</literal> and/or
+ <literal moreinfo="none">@DescribedAs</literal> annotations.</para>
+ </sect2>
+
+ <sect2>
+ <title>How to hide a collection</title>
+
+ <para>See 'Properties: How to hide a property'. The same approaches
+ work for collections.</para>
+ </sect2>
+
+ <sect2>
+ <title>How to create a derived collection</title>
+
+ <para>Collections can be derived, in the same way as properties.
+ These are not persisted, but are represented as read only
+ collections. For example:</para>
+
+ <programlisting format="linespecific">public class Department {
+ // Standard collection
+ List<Employee> employees = new ArrayList<Employee>();
+ public List<Employee> getEmployees() { ... }
+ private void setEmployees(List<Employee>) { ... }
+ void addToEmployees(final Employee employee) { ... }
+ void removeFromEmployees(final Employee employee) { ... }
+
+ // Derived collection
+ public List<Employee> getTerminatedEmployees() {
+ List<Employee> terminatedEmployees = new ArrayListt<Employee>();
+ for(Employee e: employees) {
+ if (e.isTerminated()) {
+ addTo(terminatedEmployees, e);
+ }
+ }
+ return terminatedEmployees;
+ }
+}</programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec.Actions">
<title>Actions</title>
<para>An 'action' is a method that we expect the user to be able to
@@ -1104,321 +1415,163 @@ public void modifyAmount(int amount) {
responsibility to provide this feedback to the user. For
example:</para>
- <programlisting format="linespecific">public class Customer {
- public Order placeOrder(Product p, int quantity) { ... }
- public String disablePlaceOrder(Product p, int quantity) {
- return isBlackListed()?
- "Blacklisted customers cannot place orders"
- :null;
- }</programlisting>
-
- <para>It is also possible to permanently disable an action using
- the <literal moreinfo="none">@Disabled</literal> annotation. One
- possible reason for doing this might be during prototyping - to
- indicate to the user that an action is planned, but has not yet
- been implemented.</para>
- </sect3>
-
- <sect3>
- <title>Disabling an action for certain users or roles</title>
-
- <para>See 'Properties: Disabling a property for specific users or
- roles'. The same technique can be applied to actions. However, the
- caveats apply.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>How to control the order in which actions appear on the
- menu</title>
-
- <para>Use the <literal moreinfo="none">@MemberOrder</literal>
- annotation.</para>
- </sect2>
-
- <sect2>
- <title>How to hide actions</title>
-
- <sect3>
- <title>Hiding an action always</title>
-
- <para>Use the <literal moreinfo="none">@Hidden</literal>
- annotation. (This is generally used where a <literal
- moreinfo="none">public</literal> method on an object is not
- intended to be a user action).</para>
- </sect3>
-
- <sect3>
- <title>Hiding an action under certain conditions</title>
-
- <para>A <literal moreinfo="none">hide</literal> method can be used
- to indicate that an action should be hidden under certain
- conditions. The syntax is:</para>
-
- <para><programlisting>public boolean hide<ActionName>([<parameter type> param]...)</programlisting></para>
-
- <para>A <literal moreinfo="none">true</literal> return value
- indicates that the action should not be shown. For example:</para>
-
- <programlisting format="linespecific">public class Order {
-
- public void applyDiscount(int percentage) { ... }
-
- public boolean hideApplyDiscount() {
- return isWholesaleOrder();
- }
-}</programlisting>
- </sect3>
-
- <sect3>
- <title>Hiding an action for certain users or roles</title>
-
- <para>See 'Properties: Hiding a property for specific users or
- roles'. The same technique can be applied to actions. However, the
- caveats apply.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>How to pass a message back to the user</title>
-
- <para>Sometimes, within an action it is necessary or desirable to
- pass a message to the user, for example to inform them of the
- results of their action ('5 payments have been issued') or that the
- action was not successful ('No Customer found with name John
- Smith'). <code>DomainObjectContainer</code> defines two methods for
- this purpose:</para>
-
- <para><programlisting>void informUser(String message)
-
-void warnUser(String message)</programlisting></para>
-
- <para>These two methods provide different ways to send a message to
- the user, representing increasing levels of severity. How each of
- these messages is rendered visible to the user is determined by the
- framework.</para>
-
- <para>These two methods are also available on
- <classname>AbstractDomainObject </classname>as a shortcut.</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Collections</title>
-
- <para>A collection is a list of references to several entity objects
- that have a common type.</para>
-
- <sect2>
- <title>How to add a collection to an object</title>
-
- <para>A collection is recognized via an accessor/mutator method pair
- (<code>get</code> and set) for any type of collection provided by
- the programming language. The syntax is:</para>
-
- <para><programlisting>public <collection type> get<CollectionName>()
-
-private void set<CollectionName>(<collection type> param)</programlisting></para>
-
- <para>It is recommended that the collections be specified using
- generics (for example: <literal
- moreinfo="none">List<Customer></literal> ). That way the
- framework will be able to display the collection based on that type
- definition. (Generics are also required by some persistence
- mechanisms). For example the viewer might display the collection as
- a table, with the columns defined by the visible properties of that
- type. The viewer will then automatically prevent the user from
- adding objects not of that type. If generics are not used then the
- type may be inferred from the <literal
- moreinfo="none">addTo</literal> / <literal
- moreinfo="none">removeFrom</literal> methods, if specified (see
- below).</para>
-
- <para>For example:</para>
-
- <programlisting format="linespecific">public class Employee { ... }
-
-public class Department {
- private List<Employee> employees = new ArrayList<Employee>();
- public List <Employee> getEmployees() {
- return employees;
- }
- private void setEmployees(List<Employee> employees) {
- this.employees = employees;
- }
- ...
-}</programlisting>
- </sect2>
-
- <sect2>
- <title>How to trigger other behaviour when an object is added or
- removed</title>
-
- <para>A collection may have a corresponding <literal
- moreinfo="none">addTo</literal> and/or <literal
- moreinfo="none">removeFrom</literal> method. This is equivalent to
- the <literal moreinfo="none">modify</literal> and <literal
- moreinfo="none">clear</literal> methods for properties. The syntax
- is:</para>
-
- <para><programlisting>public void addTo<CollectionName>(<entity type> param)
-
-public void removeFrom<CollectionName>(<entity type> param)</programlisting></para>
-
- <para>where <literal moreinfo="none"><entity type></literal>
- is the same type as the generic collection type. For example:</para>
-
- <programlisting format="linespecific">public class Employee { ... }
+ <programlisting format="linespecific">public class Customer {
+ public Order placeOrder(Product p, int quantity) { ... }
+ public String disablePlaceOrder(Product p, int quantity) {
+ return isBlackListed()?
+ "Blacklisted customers cannot place orders"
+ :null;
+ }</programlisting>
-public class Department {
- private List<Employee> employees = new ArrayList<Employee>();
- public List <Employee> getEmployees() {
- return employees;
- }
- private void setEmployees(List<Employee> employees) {
- this.employees = employees;
- }
- public void addToEmployees(Employee employee) {
- employees.add(employee);
- }
- public void removeFromEmployees(Employee employee) {
- employees.remove(employee);
- }
+ <para>It is also possible to permanently disable an action using
+ the <literal moreinfo="none">@Disabled</literal> annotation. One
+ possible reason for doing this might be during prototyping - to
+ indicate to the user that an action is planned, but has not yet
+ been implemented.</para>
+ </sect3>
- ...
-}</programlisting>
+ <sect3>
+ <title>Disabling an action for certain users or roles</title>
- <para>The addTo / removeFrom and modify / clear methods are
- particularly useful in setting up bidirectional relationships using
- the 'mutual registration pattern'; for a write-up of this pattern,
- see <ulink
- url="???">http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf</ulink>.</para>
+ <para>See 'Properties: Disabling a property for specific users or
+ roles'. The same technique can be applied to actions. However, the
+ caveats apply.</para>
+ </sect3>
</sect2>
<sect2>
- <title>How to prevent the user from modifying a collection</title>
+ <title>How to control the order in which actions appear on the
+ menu</title>
- <para>Preventing the user from adding to or removing from a
- collection is known as 'disabling' the collection.</para>
+ <para>Use the <literal moreinfo="none">@MemberOrder</literal>
+ annotation.</para>
+ </sect2>
+
+ <sect2>
+ <title>How to hide actions</title>
<sect3>
- <title>Disabling a collection permanently</title>
+ <title>Hiding an action always</title>
- <para>Use the <literal moreinfo="none">@Disabled</literal>
- annotation.</para>
+ <para>Use the <literal moreinfo="none">@Hidden</literal>
+ annotation. (This is generally used where a <literal
+ moreinfo="none">public</literal> method on an object is not
+ intended to be a user action).</para>
</sect3>
<sect3>
- <title>Disabling a collection under certain conditions</title>
+ <title>Hiding an action under certain conditions</title>
- <para>A <literal moreinfo="none">disable</literal> method can be
- used to disable a particular instance's collection under certain
- conditions: The syntax is:</para>
+ <para>A <literal moreinfo="none">hide</literal> method can be used
+ to indicate that an action should be hidden under certain
+ conditions. The syntax is:</para>
- <para><literal moreinfo="none">public String
- disable<CollectionName>()</literal> For example:</para>
+ <para><programlisting>public boolean hide<ActionName>([<parameter type> param]...)</programlisting></para>
- <programlisting format="linespecific">public class Department {
- public List<Employee> getEmployees() { ... }
- public void addToEmployees(Employee employee) { ... }
- public void removeFromEmployees(Employee employee) { ... }
- public void disableEmployees() {
- return isClosed()? "This department is closed" : null;
+ <para>A <literal moreinfo="none">true</literal> return value
+ indicates that the action should not be shown. For example:</para>
+
+ <programlisting format="linespecific">public class Order {
+
+ public void applyDiscount(int percentage) { ... }
+
+ public boolean hideApplyDiscount() {
+ return isWholesaleOrder();
}
}</programlisting>
</sect3>
<sect3>
- <title>Disabling a collection for specific users or roles</title>
+ <title>Hiding an action for certain users or roles</title>
- <para>See Properties: Disabling a property for specific users or
- roles'. The same technique can be applied to collections, with the
- same caveats applying.</para>
+ <para>See 'Properties: Hiding a property for specific users or
+ roles'. The same technique can be applied to actions. However, the
+ caveats apply.</para>
</sect3>
</sect2>
<sect2>
- <title>How to validate an object to be added or removed</title>
+ <title>How to pass a message back to the user</title>
- <para>A <literal moreinfo="none">validate</literal> method is used
- to check that an object to be added or removed from a collection is
- valid. A non-null return <code>String</code> indicates the reason
- why the object cannot be added/removed, and the viewing mechanism
- will display this to the user. The syntax is:</para>
+ <para>Sometimes, within an action it is necessary or desirable to
+ pass a message to the user, for example to inform them of the
+ results of their action ('5 payments have been issued') or that the
+ action was not successful ('No Customer found with name John
+ Smith'). <code>DomainObjectContainer</code> defines two methods for
+ this purpose:</para>
- <para><programlisting>public String validateAddTo<CollectionName>(<property type> param)
+ <para><programlisting>void informUser(String message)
-public String validateRemoveFrom<CollectionName>(<property type> param)</programlisting></para>
+void warnUser(String message)</programlisting></para>
- <para>For example:</para>
+ <para>These two methods provide different ways to send a message to
+ the user, representing increasing levels of severity. How each of
+ these messages is rendered visible to the user is determined by the
+ framework.</para>
- <programlisting format="linespecific">public class Department {
- private List<Employee> employees = new ArrayList<Employee>();
- public List<Employee> getEmployees() { ... }
- private void setEmployees(List<Employee> employees) { ... }
- public String validateAddToEmployee(Employee employee) {
- return employee.isRetired()?
- "Cannot add retired employees to department"
- :null;
-}</programlisting>
+ <para>These two methods are also available on
+ <classname>AbstractDomainObject </classname>as a shortcut.</para>
</sect2>
+ </sect1>
- <sect2>
- <title>How to control the order in which collections are
- displayed</title>
+ <sect1 id="sec.MustSpecify">
+ <title>@MustSatisfy Specification</title>
- <para>Use the <literal moreinfo="none">@MemberOrder</literal>
- annotation.</para>
- </sect2>
+ <para>The <literal>@MustSatisfy</literal> annotation is an alternative
+ to using imperative validation, allowing validation rules to be
+ captured in an (implementation of a)
+ <classname>org.apache.isis.applib.spec.Specification</classname>.</para>
- <sect2>
- <title>How to specify a name and/or description for a
- collection</title>
+ <para>For example:</para>
- <para>Use the <literal moreinfo="none">@Named</literal> and/or
- <literal moreinfo="none">@DescribedAs</literal> annotations.</para>
- </sect2>
+ <programlisting format="linespecific">public class DomainObjectWithMustSatisfyAnnotations extends AbstractDomainObject {
- <sect2>
- <title>How to hide a collection</title>
+ private String lastName;
+ @MustSatisfy(SpecificationRequiresFirstLetterToBeUpperCase.class)
+ public String getLastName() {
+ resolve(lastName);
+ return lastName;
+ }
+ public void setLastName(String lastName) {
+ this.lastName = lastName;
+ objectChanged();
+ }
- <para>See 'Properties: How to hide a property'. The same approaches
- work for collections.</para>
- </sect2>
+ public void changeLastName(
+ @MustSatisfy(SpecificationRequiresFirstLetterToBeUpperCase.class)
+ String lastName
+ ) {
+ setLastName(lastName);
+ }
- <sect2>
- <title>How to create a derived collection</title>
+}</programlisting>
- <para>Collections can be derived, in the same way as properties.
- These are not persisted, but are represented as read only
- collections. For example:</para>
+ <para><remark>TODO: @MustSatisfy may not work for action parameters;
+ see <ulink
+ url="???">http://dev.isis.apache.org/trac/ticket/669</ulink>.</remark></para>
+ </sect1>
+ </chapter>
- <programlisting format="linespecific">public class Department {
- // Standard collection
- List<Employee> employees = new ArrayList<Employee>();
- public List<Employee> getEmployees() { ... }
- private void setEmployees(List<Employee>) { ... }
- void addToEmployees(final Employee employee) { ... }
- void removeFromEmployees(final Employee employee) { ... }
+ <chapter>
+ <title>Repositories, Factories, Services and Values</title>
- // Derived collection
- public List<Employee> getTerminatedEmployees() {
- List<Employee> terminatedEmployees = new ArrayListt<Employee>();
- for(Employee e: employees) {
- if (e.isTerminated()) {
- addTo(terminatedEmployees, e);
- }
- }
- return terminatedEmployees;
- }
-}</programlisting>
- </sect2>
- </sect1>
+ <abstract>
+ <para>How-to's relating to the everything else that goes into making
+ up an <emphasis>Isis</emphasis> application.</para>
+ </abstract>
- <sect1>
+ <para>This chapter contains how-to's for programming conventions that
+ apply to everything that isn't a domain object (ie "everything else")
+ that also makes up an <emphasis>Apache Isis</emphasis> application.
+ Specifically, we're talking about repositories and factories (<xref
+ linkend="sec.RepositoriesAndFactories" />), services (<xref
+ linkend="sec.Services" />) and values (<xref
+ linkend="sec.ValueTypes" />).</para>
+
+ <sect1 id="sec.RepositoriesAndFactories">
<title>Repositories and Factories</title>
- <para>The [[NAME]] application library provides a class</para>
+ <para>The Apache Isis application library provides a class</para>
<para><literal
moreinfo="none">org.apache.isis.applib.AbstractFactoryAndRepository</literal></para>
@@ -1475,7 +1628,7 @@ public String validateRemoveFrom<Coll
</sect2>
</sect1>
- <sect1>
+ <sect1 id="sec.Services">
<title>Registering services</title>
<sect2>
@@ -1510,44 +1663,7 @@ public String validateRemoveFrom<Coll
</sect2>
</sect1>
- <sect1>
- <title>@MustSatisfy specification</title>
-
- <para>The <literal>@MustSatisfy</literal> annotation is an alternative
- to using imperative validation, allowing validation rules to be
- captured in an (implementation of a)
- <classname>org.apache.isis.applib.spec.Specification</classname>.</para>
-
- <para>For example:</para>
-
- <programlisting format="linespecific">public class DomainObjectWithMustSatisfyAnnotations extends AbstractDomainObject {
-
- private String lastName;
- @MustSatisfy(SpecificationRequiresFirstLetterToBeUpperCase.class)
- public String getLastName() {
- resolve(lastName);
- return lastName;
- }
- public void setLastName(String lastName) {
- this.lastName = lastName;
- objectChanged();
- }
-
- public void changeLastName(
- @MustSatisfy(SpecificationRequiresFirstLetterToBeUpperCase.class)
- String lastName
- ) {
- setLastName(lastName);
- }
-
-}</programlisting>
-
- <para><remark>TODO: @MustSatisfy may not work for action parameters;
- see <ulink
- url="???">http://dev.isis.apache.org/trac/ticket/669</ulink>.</remark></para>
- </sect1>
-
- <sect1>
+ <sect1 id="sec.ValueTypes">
<title>Value Types</title>
<para>In addition to the built-in value types it is also possible to
@@ -1585,38 +1701,20 @@ public class Money extends Magnitude {
than the @Value annotation; this is particularly useful for
third-party value types.</remark></para>
</sect1>
-
- <sect1>
- <title>Resolve and ObjectChanged</title>
-
- <para>In previous versions of the framework it was necessary to call
- the inherited <methodname>resolve()</methodname> method within every
- property or collection's getter, and
- <methodname>objectChanged()</methodname> within every property's
- setter and every collection's addTo or removeFrom.</para>
-
- <para>These methods still exist in
- <classname>AbstractDomainObject</classname>, but no longer need to be
- called explicitly. Instead [[NAME]] 4.0 uses bytecode enhancement
- (using either cglib or javassist) to automatically call these methods.
- This bytecode enhancement can be disabled in
- <filename>isis.properties</filename> file; if it is then the methods
- must be called manually as they were in [[NAME]] 3.0.</para>
- </sect1>
</chapter>
</part>
<part>
- <title>Reference</title>
+ <title>Reference Appendices</title>
- <chapter id="sec.RecognisedTypes">
+ <appendix id="sec.RecognisedTypes">
<title>Recognised Types</title>
<abstract>
<para>*** yada yada</para>
</abstract>
- <para>[[NAME]] creates an adapter for every domain object. There are
+ <para>Apache Isis creates an adapter for every domain object. There are
three categories of objects that are recognised: value, reference and
collection. Value and collection objects are dealt with on a class by
class basis, while all reference objects are dealt with in the same way
@@ -1821,9 +1919,9 @@ public class Money extends Magnitude {
</listitem>
</itemizedlist>
</sect1>
- </chapter>
+ </appendix>
- <chapter>
+ <appendix>
<title>Recognized Methods and Method Prefixes</title>
<abstract>
@@ -2036,8 +2134,8 @@ public String disable<actionName>(
<para>A standard JavaBean accessor/mutator pair will be recognised as
a field for a value or reference. Values include Java primitives,
<classname>String</classname>s and <classname>Date</classname>s, and
- also the value types provided by the [[NAME]] application library (see
- the section on <xref linkend="sec.RecognisedTypes" />).</para>
+ also the value types provided by the Apache Isis application library
+ (see the section on <xref linkend="sec.RecognisedTypes" />).</para>
<para>If there is no mutator method then the field is flagged as being
derived and will not be persisted or editable.</para>
@@ -2441,9 +2539,9 @@ public String validateRemoveFrom<Prop
<code>validate</code> method.</para>
</warning>
</sect1>
- </chapter>
+ </appendix>
- <chapter>
+ <appendix>
<title>Recognized Annotations</title>
<abstract>
@@ -2457,7 +2555,7 @@ public String validateRemoveFrom<Prop
<para></para>
<para>This section defines the set of annotations that are recognised by
- the [[NAME]] Java Programming Model.</para>
+ the Apache Isis Java Programming Model.</para>
<sect1>
<title>@ActionOrder</title>
@@ -3195,9 +3293,9 @@ public class InputForm {
<sect1>
<title>@Plural</title>
- <para>Where [[NAME]] displays a collection of several objects it may
- use the plural form of the object type in the title. By default the
- plural name will be created by adding an 's' to the end of the
+ <para>Where Apache Isis displays a collection of several objects it
+ may use the plural form of the object type in the title. By default
+ the plural name will be created by adding an 's' to the end of the
singular name (whether that is the class name or another name
specified using <literal moreinfo="none">@Named</literal>). Where the
single name ends in 'y' then the default plural name will end in 'ies'
@@ -3309,20 +3407,20 @@ public class ComplexNumber {
framework to interact with the value, parsing strings and displaying
as text, and encoding/decoding (for serialization).</para>
</sect1>
- </chapter>
+ </appendix>
- <chapter>
+ <appendix>
<title>DomainObjectContainer</title>
<para></para>
<para>*** there was only ever a placeholder in the original NOF doc for
- a chapter on this topic.</para>
+ a appendix on this topic.</para>
<para></para>
- </chapter>
+ </appendix>
- <chapter>
+ <appendix>
<title>Supporting Classes</title>
<para></para>
@@ -3368,9 +3466,9 @@ public class ComplexNumber {
<para>***</para>
</sect2>
</sect1>
- </chapter>
+ </appendix>
- <chapter>
+ <appendix>
<title>Configuring via Properties</title>
<para></para>
@@ -3610,6 +3708,6 @@ public class ComplexNumber {
</sect3>
</sect2>
</sect1>
- </chapter>
+ </appendix>
</part>
</book>