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 2013/09/12 10:36:04 UTC

svn commit: r1522483 - in /isis/site/trunk/content/applib-guide: how-tos/ reference/

Author: danhaywood
Date: Thu Sep 12 08:36:03 2013
New Revision: 1522483

URL: http://svn.apache.org/r1522483
Log:
more on newTransientInstance; better linking from recognized methods etc

Modified:
    isis/site/trunk/content/applib-guide/how-tos/how-to-01-160-How-to-create-or-delete-objects-within-your-code.md
    isis/site/trunk/content/applib-guide/how-tos/how-to-03-020-How-to-specify-a-set-of-choices-for-an-action-parameter.md
    isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md
    isis/site/trunk/content/applib-guide/reference/Recognized-Methods-and-Prefixes.md

Modified: isis/site/trunk/content/applib-guide/how-tos/how-to-01-160-How-to-create-or-delete-objects-within-your-code.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/how-tos/how-to-01-160-How-to-create-or-delete-objects-within-your-code.md?rev=1522483&r1=1522482&r2=1522483&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/how-tos/how-to-01-160-How-to-create-or-delete-objects-within-your-code.md (original)
+++ isis/site/trunk/content/applib-guide/how-tos/how-to-01-160-How-to-create-or-delete-objects-within-your-code.md Thu Sep 12 08:36:03 2013
@@ -6,20 +6,18 @@ important that the framework is made awa
 object - in order that it may be persisted to the object store, and in
 order that any services that the new object needs are injected into it.
 
-Just specifying `new
-        Customer()`, for example, will create a Customer object, but
-that object will *not* be known to the framework. However, since we do
-not want to tie our domain objects to a particular framework, we use the
+Just specifying `new Customer()`, for example, will create a `Customer` object, but that object will *not* be known to the framework.  Such an object *can* (as of `1.3.0-SNAPSHOT`) be persisted by the framework.  However any services will not be injected into the object until such time.  Also, the [default value for any properties](how-to-03-017-How-to-specify-default-value-of-an-object-property.html) will not be setup, nor will the [created callback](how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html) be called.
+
+Therefore, the recommended way to instantiate an object (and mandatory prior to `1.3.0-SNAPSHOT`) is to do so through the framework.  However, since we do
+not want to couple our domain objects too closely to Isis, we use the
 idea of a 'container' to mediate, specified by the
-`org.apache.isis.applib.DomainObjectContainer` interface. See ? for the
-full list of methods provided by DomainObjectContainer.
+`org.apache.isis.applib.DomainObjectContainer` interface. The
+full list of methods provided by `DomainObjectContainer` can be found [here](../reference/DomainObjectContainer.html).
 
 This interface defines the following methods for managing domain
 objects:
 
--   `<T> T
-                newTransientInstance(final Class<T>
-                ofClass)`
+-   `<T> T newTransientInstance(final Class<T> ofClass)`
 
     Returns a new instance of the specified class, that is transient
     (unsaved). The object may subsequently be saved either by the user
@@ -27,40 +25,39 @@ objects:
     object view) or programmatically by calling `persist(Object
                 transientObject)`
 
--   \<T\> T newPersistentInstance(final Class\<T\> ofClass)
+-   `<T> T newPersistentInstance(final Class<T> ofClass)`
 
     Creates a new object already persisted.
 
--   boolean isPersistent()
+-   `boolean isPersistent()`
 
     Checks whether an object has already been persisted. This is often
     useful in controlling visibility or availability of properties or
     actions.
 
--   void persist(Object transientObject)
+-   `void persist(Object transientObject)`
 
-    Persists a transient object (created using
-    newTransientInstance(...), see above).
+    Persists a transient object (created using `newTransientInstance(...)`, see above).
 
--   void persistIfNotAlready(Object domainObject)
+-   `void persistIfNotAlready(Object domainObject)`
 
     It is an error to persist an object if it is already persistent;
     this method will persist only if the object is not already
     persistent (otherwise it will do nothing).
 
--   void remove(Object persistentObject)
+-   `void remove(Object persistentObject)`
 
     Removes (deletes) from the object store, making the reference
     transient.
 
--   void removeIfNotAlready(Object domainObject)
+-   `void removeIfNotAlready(Object domainObject)`
 
     It is an error to remove an object if it is not persistent; this
     method will remove only if the object is known to be persistent
     (otherwise it will do nothing).
 
 A domain object specifies that it needs to have a reference to the
-DomainObjectContainer injected into by including the following code:
+`DomainObjectContainer` injected into by including the following code:
 
     private DomainObjectContainer container;
     protected DomainObjectContainer getContainer() {
@@ -71,7 +68,11 @@ DomainObjectContainer injected into by i
     }
 
 Creating or deleting objects is then done by invoking those methods on
-the container. For example the following code would then create a new
+the container. 
+
+###Examples
+
+The following code would then create a new
 Customer object within another method:
 
     Customer newCust = getContainer().newTransientInstance(Customer.class);
@@ -87,16 +88,15 @@ access to those methods, so the code wou
     persist(newCust);
 
 As an alternative to putting the creation logic within your domain
-objects, you could alternatively delegate to an injected factory (see
-?). Ultimately factories just delegate back to DomainObjectContainer in
+objects, you could alternatively delegate to an injected service. Ultimately factories just delegate back to `DomainObjectContainer` in
 the same way, so from a technical standpoint there is little difference.
 However it is generally worth introducing a factory because it provides
 a place to centralize any business logic. It also affords the
-opportunity to introduce a domain term (eg ProductCatalog or
-StudentRegister), thereby reinforcing the "ubiquitous language".
+opportunity to introduce a domain term (eg `ProductCatalog` or
+`StudentRegister`), thereby reinforcing the "ubiquitous language".
 
 These methods are actually provided by the
-org.apache.isis.applib.AbstractContainedObject and so are also available
+`org.apache.isis.applib.AbstractContainedObject` and so are also available
 on `org.apache.isis.applib.AbstractService` (and, hence, on
 `org.apache.isis.applib.AbstractFactoryAndRepository`) for creating
 objects within a service.
@@ -114,7 +114,7 @@ objects within a service.
 > state.
 >
 > The recommended approach is, if possible, to mark these supplementary
-> classes as not persistable by the user (see ?), or not to permit the
+> classes as not persistable by the user, or not to permit the
 > user to create a new transient object that is a child of an existing
 > transient object, but, rather, to require the user to save the parent
 > object first.

Modified: isis/site/trunk/content/applib-guide/how-tos/how-to-03-020-How-to-specify-a-set-of-choices-for-an-action-parameter.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/how-tos/how-to-03-020-How-to-specify-a-set-of-choices-for-an-action-parameter.md?rev=1522483&r1=1522482&r2=1522483&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/how-tos/how-to-03-020-How-to-specify-a-set-of-choices-for-an-action-parameter.md (original)
+++ isis/site/trunk/content/applib-guide/how-tos/how-to-03-020-How-to-specify-a-set-of-choices-for-an-action-parameter.md Thu Sep 12 08:36:03 2013
@@ -12,6 +12,8 @@ will automatically be offered the full s
 If this isn't the case, then - as for defaults - there are two different
 ways to specify parameters; either per parameter, or for all parameters.
 
+> **Note** Dependent choices, whereby the values are dependent on another action parameter, are [also supported](how-to-03-022-How-to-specify-dependent-choices-for-action-parameters.html).
+
 ### Per parameter syntax (preferred)
 
 The per-parameter form is simpler and generally preferred.

Modified: isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md?rev=1522483&r1=1522482&r2=1522483&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md (original)
+++ isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md Thu Sep 12 08:36:03 2013
@@ -8,6 +8,8 @@ The `DomainObjectContainer` interface pr
 from domain objects into the *Isis* framework. It can also be used as a
 lightweight general purpose repository during prototyping.
 
+The following table lists the most important (ie non deprecated) methods in this interface.
+
 <table>
 <tr>
     <th>Category</th>
@@ -16,17 +18,13 @@ lightweight general purpose repository d
 </tr>
 <tr>
     <td>Object creation</td>
-    <td>newTransientInstance(Class\<T\>)</td>
-    <td>Creates new non-persisted object</td>
-</tr>
-<tr>
-    <td></td>
-    <td>newPersistentInstance(Class\<T\>)</td>
-    <td>Creates new object, will be persisted at end of action</td>
+    <td>newTransientInstance(Class&lt;T>)</td>
+    <td>Creates new non-persisted object.  
+        <p>While it is also possible to simply <i>new()</i> up an object, that object will not have any services injected into it, nor will any properties be defaulted nor will any <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html"><i>created()</i></a> callback be invoked.</td>
 </tr>
 <tr>
     <td></td>
-    <td>newInstance(Class\<T\>, Object)</td>
+    <td>newInstance(Class&lt;T>, Object)</td>
     <td>Creates object in state persistence state as that provided</td>
 </tr>
 <tr>
@@ -41,7 +39,7 @@ lightweight general purpose repository d
 </tr>
 <tr>
     <td>Generic Repository</td>
-    <td>allInstances(Class\<T\>)</td>
+    <td>allInstances(Class&lt;T>)</td>
     <td>All persisted instances of specified type</td>
 </tr>
 <tr>

Modified: isis/site/trunk/content/applib-guide/reference/Recognized-Methods-and-Prefixes.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/Recognized-Methods-and-Prefixes.md?rev=1522483&r1=1522482&r2=1522483&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/Recognized-Methods-and-Prefixes.md (original)
+++ isis/site/trunk/content/applib-guide/reference/Recognized-Methods-and-Prefixes.md Thu Sep 12 08:36:03 2013
@@ -12,7 +12,7 @@ recognized by *Apache Isis*' default pro
     <th>Collection</th>
     <th>Action</th>
     <th>Action Param</th>
-    <th>See also</th>
+    <th>Description</th>
 </tr>
 <tr>
     <td>addTo</td>
@@ -21,7 +21,7 @@ recognized by *Apache Isis*' default pro
     <td>Y</td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>add object to a collection (nb: not currently supported by Wicket viewer)<p>See also <tt>removeFrom</tt></td>
 </tr>
 <tr>
     <td>removeFrom</td>
@@ -30,7 +30,7 @@ recognized by *Apache Isis*' default pro
     <td>Y</td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>remove object from a collection (nb: not currently supported by Wicket viewer)<p>See also <tt>addTo</tt></td>
 </tr>
 <tr>
     <td>choices</td>
@@ -39,16 +39,16 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td>Y</td>
-    <td></td>
+    <td>Provide list of choices for a <a href="../how-tos/how-to-03-010-How-to-specify-a-set-of-choices-for-a-property.html">property</a> or <a href="../how-tos/how-to-03-020-How-to-specify-a-set-of-choices-for-an-action-parameter.html">action</a> <a href="../how-tos/how-to-03-022-How-to-specify-dependent-choices-for-action-parameters.html">parameter</a><p>See also <tt>autoComplete</tt>.</td>
 </tr>
 <tr>
-    <td>autoComplete<br/>[1.3.0-SNAPSHOT]</td>
+    <td>autoComplete<p/>[1.3.0-SNAPSHOT]</td>
     <td></td>
     <td>Y</td>
     <td></td>
     <td></td>
     <td>Y</td>
-    <td><a href="../recognized-annotations/AutoComplete.html">@AutoComplete </a> annotation</td>
+    <td>Return a list of matching elements for a <a href="../how-tos/how-to-03-015-How-to-specify-an-autocomplete-for-a-property.html">property</a> or an <a href="../how-tos/how-to-03-025-How-to-specify-an-autocomplete-for-an-action-parameter.html">action parameter</a>.  <p>Alternatively, can specify for a class using the <a href="../recognized-annotations/AutoComplete.html">@AutoComplete </a> annotation.<p>See also <tt>choices</tt></td>
 </tr>
 <tr>
     <td>clear</td>
@@ -57,7 +57,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Clear a property (set it to null).  Allows business logic to be placed apart from the setter.<p>See also <tt>modify</tt></td>
 </tr>
 <tr>
     <td>modify</td>
@@ -66,7 +66,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Modify a property (set it to a non-null) value.  Allows business logic to be placed apart from the setter.<p>See also <tt>clear</tt>.</td>
 </tr>
 <tr>
     <td>created</td>
@@ -75,7 +75,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the object has just been <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">created</a> using <tt>newTransientInstance()</tt></td>
 </tr>
 <tr>
     <td>default</td>
@@ -84,7 +84,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td>Y</td>
-    <td></td>
+    <td>Default value for a <a href="../how-tos/how-to-03-017-How-to-specify-default-value-of-an-object-property.html">property</a> or an <a href="../how-tos/how-to-03-050-How-to-specify-default-values-for-an-action-parameter.html">action parameter</a>.</td>
 </tr>
 <tr>
     <td>disable</td>
@@ -93,7 +93,7 @@ recognized by *Apache Isis*' default pro
     <td>Y</td>
     <td>Y</td>
     <td></td>
-    <td></td>
+    <td>Disables (makes read-only) a <a href="../how-tos/how-to-02-050-How-to-prevent-a-property-from-being-modified.html">property</a>, a <a href="../how-tos/how-to-02-060-How-to-prevent-a-collection-from-being-modified.html">collection</a> or an <a href="../how-tos/how-to-02-070-How-to-prevent-an-action-from-being-invoked.html">action</a>.</td>
 </tr>
 <tr>
     <td>get</td>
@@ -102,7 +102,7 @@ recognized by *Apache Isis*' default pro
     <td>Y</td>
     <td></td>
     <td></td>
-    <td>set</td>
+    <td>Access the value of a property or collection.<p>See also <tt>set</tt>.</td>
 </tr>
 <tr>
     <td>getId</td>
@@ -111,7 +111,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td>(services only)</td>
+    <td>Provides an optional unique identifier of a service.<p>If not provided, the services fully-qualified class name is used.</td>
 </tr>
 <tr>
     <td>hide</td>
@@ -120,7 +120,7 @@ recognized by *Apache Isis*' default pro
     <td>Y</td>
     <td>Y</td>
     <td></td>
-    <td></td>
+    <td>Hides a <a href="../how-tos/how-to-02-010-How-to-hide-a-property.html">property</a>, a <a href="../how-tos/how-to-02-020-How-to-hide-a-collection.html">collection</a> or an <a href="../how-tos/how-to-02-030-How-to-hide-an-action.html">action</a>.</td>
 </tr>
 <tr>
     <td>iconName</td>
@@ -129,7 +129,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Provides the name of the image to render, usually alongside the title, to represent the object.  If not provided, then the class name is used to locate an image.<p>See also <tt>title</tt></td>
 </tr>
 <tr>
     <td>loaded</td>
@@ -138,7 +138,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the (persistent) object has just been <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">loaded</a> from the object store.<p>NB: this may not called by the JDO ObjectStore.</td>
 </tr>
 <tr>
     <td>loading</td>
@@ -147,16 +147,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
-</tr>
-<tr>
-    <td>modify</td>
-    <td></td>
-    <td>Y</td>
-    <td></td>
-    <td></td>
-    <td></td>
-    <td>clear</td>
+    <td>Lifecycle callback for when the (persistent) object is just about to be <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">loaded</a> from the object store.<p>NB: this may not called by the JDO ObjectStore.</td>
 </tr>
 <tr>
     <td>persisted</td>
@@ -165,7 +156,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the (persistent) object has just been <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">persisted</a> from the object store.<p>NB: this may not called by the JDO ObjectStore</td>
 </tr>
 <tr>
     <td>persisting</td>
@@ -174,7 +165,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the (persistent) object is just about to be <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">persisted</a> from the object store<p>NB: this may not called by the JDO ObjectStore in all situations</td>
 </tr>
 <tr>
     <td>removing</td>
@@ -183,7 +174,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the (persistent) object is just about to be <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">deleted</a> from the object store<p>NB: this may not called by the JDO ObjectStore in all situations</td>
 </tr>
 <tr>
     <td>removed</td>
@@ -192,16 +183,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
-</tr>
-<tr>
-    <td>removeFrom</td>
-    <td></td>
-    <td>Y</td>
-    <td></td>
-    <td></td>
-    <td></td>
-    <td>addTo</td>
+    <td>Lifecycle callback for when the (persistent) object has just been <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">persisted</a> from the object store<p>NB: this may not called by the JDO ObjectStore in all situations</td>
 </tr>
 <tr>
     <td>set</td>
@@ -210,7 +192,7 @@ recognized by *Apache Isis*' default pro
     <td>Y</td>
     <td></td>
     <td></td>
-    <td>get</td>
+    <td>Sets the value of a propery or a collection.</td>
 </tr>
 <tr>
     <td>toString</td>
@@ -219,7 +201,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Used as the fallback title for an object if there is <a href="../how-tos/how-to-01-040-How-to-specify-a-title-for-a-domain-entity.html">no <tt>title()</tt> method</a> or properties annotated with <a href="../recognized-annotations/Title.html"><tt>@Title</tt></a></td>
 </tr>
 <tr>
     <td>title</td>
@@ -228,7 +210,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td><a href="../recognized-annotations/Title.html">@Title </a> annotation</td>
+    <td>Provides a title for the object. <p>Alternatively, use the <a href="../recognized-annotations/Title.html">@Title </a> annotation.</td>
 </tr>
 <tr>
     <td>updating</td>
@@ -237,7 +219,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the (persistent) object is just about to be <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">updated</a> in the object store<p>NB: this may not called by the JDO ObjectStore in all situations</td>
 </tr>
 <tr>
     <td>updated</td>
@@ -246,7 +228,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td></td>
+    <td>Lifecycle callback for when the (persistent) object has just been <a href="../how-tos/how-to-07-070-How-to-hook-into-the-object-lifecycle-using-callbacks.html">updated</a> in the object store<p>NB: this may not called by the JDO ObjectStore in all situations</td>
 </tr>
 <tr>
     <td>validate</td>
@@ -255,7 +237,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td>Y</td>
     <td>Y</td>
-    <td></td>
+    <td>Check that a proposed value of a <a href="../how-tos/how-to-02-100-How-to-validate-user-input-for-a-property.html>property</a> or an <a href="../how-tos/how-to-02-120-How-to-validate-an-action-parameter-argument.html>action parameter> is valid.<p>See also <tt>validateAddTo</tt> and <tt>validateRemoveFrom</tt> for collections.</td>
 </tr>
 <tr>
     <td>validateAddTo</td>
@@ -264,7 +246,7 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td>validateRemoveFrom</td>
+    <td>Check that a proposed object to add to a <a href="../how-tos/how-to-02-110-How-to-validate-an-object-being-added-or-removed-from-a-collection.html">collection</a> is valid.<p>See also <tt>validateRemoveFrom</tt>, and <tt>validate</tt> for properties and collections.</td>
 </tr>
 <tr>
     <td>validateRemoveFrom</td>
@@ -273,12 +255,12 @@ recognized by *Apache Isis*' default pro
     <td></td>
     <td></td>
     <td></td>
-    <td>validateAddTo</td>
+    <td>Check that a proposed object to add to a <a href="../how-tos/how-to-02-110-How-to-validate-an-object-being-added-or-removed-from-a-collection.html">collection</a> is valid.<p>See also <tt>validateAddTo</tt>, and <tt>validate</tt> for properties and collections.</td>
 </tr>
 </table>
 
 
-There are also a number of deprecated methods:
+There are also a number of deprecated methods (for lifecycle callbacks):
 
 <table>
 <tr>
@@ -297,7 +279,7 @@ There are also a number of deprecated me
     <td></td>
     <td></td>
     <td></td>
-    <td>removed</td>
+    <td>Replaced by <tt>removed</tt></td>
 </tr>
 <tr>
     <td>deleting</td>
@@ -306,7 +288,7 @@ There are also a number of deprecated me
     <td></td>
     <td></td>
     <td></td>
-    <td>removing</td>
+    <td>Replaced by <tt>removing</tt></td>
 </tr>
 <tr>
     <td>saved</td>
@@ -315,7 +297,7 @@ There are also a number of deprecated me
     <td></td>
     <td></td>
     <td></td>
-    <td>persisted</td>
+    <td>Replaced by <tt>persisted</tt></td>
 </tr>
 <tr>
     <td>saving</td>
@@ -324,7 +306,7 @@ There are also a number of deprecated me
     <td></td>
     <td></td>
     <td></td>
-    <td>persisting</td>
+    <td>Replaced by <tt>persisting</tt></td>
 </tr>
 </table>