You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/10/07 09:22:20 UTC
[1/2] isis git commit: ISIS-1195: adding some missing documentation,
improving javadoc.
Repository: isis
Updated Branches:
refs/heads/master 2162891e8 -> 7ecb94853
ISIS-1195: adding some missing documentation, improving javadoc.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ecc32623
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ecc32623
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ecc32623
Branch: refs/heads/master
Commit: ecc32623323f2d47f306dd78f62c13eb75b9fc23
Parents: 2162891
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Oct 7 08:17:07 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Oct 7 08:17:07 2015 +0100
----------------------------------------------------------------------
.../asciidoc/guides/_cg_asciidoc-templates.adoc | 4 +-
...s_super_manpage-AbstractContainedObject.adoc | 25 +-
...asses_super_manpage-AbstractDomainEvent.adoc | 11 +-
...sses_super_manpage-AbstractDomainObject.adoc | 7 +-
...ses_super_manpage-AbstractDomainService.adoc | 9 -
...er_manpage-AbstractFactoryAndRepository.adoc | 8 +-
...g_classes_super_manpage-AbstractService.adoc | 5 +-
...classes_super_manpage-AbstractViewModel.adoc | 8 +-
...classes_super_manpage-ActionDomainEvent.adoc | 13 +-
...ses_super_manpage-CollectionDomainEvent.adoc | 14 +-
..._rg_classes_super_manpage-FixtureScript.adoc | 14 +-
...rg_classes_super_manpage-FixtureScripts.adoc | 5 +-
...asses_super_manpage-PropertyDomainEvent.adoc | 10 +-
.../guides/_rg_classes_value-types.adoc | 2 +-
.../isis/applib/AbstractContainedObject.java | 465 +++++++++++++++----
.../isis/applib/AbstractDomainObject.java | 90 ++--
.../applib/AbstractFactoryAndRepository.java | 25 +-
.../isis/applib/DomainObjectContainer.java | 230 ++++-----
.../applib/fixturescripts/FixtureScript.java | 3 +
.../applib/fixturescripts/FixtureScripts.java | 4 +
.../container/DomainObjectContainerDefault.java | 24 +-
21 files changed, 702 insertions(+), 274 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
index 3c7a9dd..a08c19c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc-templates.adoc
@@ -225,9 +225,9 @@ a hyperlink to the "man page" for a superclass, where:
for example:
-pass:[<pre>xref:rg.adoc#_rg_classes_super_manpage-AbstractDomainService[`AbstractDomainService`\]</pre>]
+pass:[<pre>xref:rg.adoc#_rg_classes_super_manpage-AbstractService[`AbstractService`\]</pre>]
-|xref:rg.adoc#_rg_classes_super_manpage-AbstractDomainService[`AbstractDomainService`]
+|xref:rg.adoc#_rg_classes_super_manpage-AbstractService[`AbstractService`]
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
index 2fd1f17..9b7facb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
@@ -4,6 +4,29 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+This class is a convenience superclass for domain objects and services, providing general purpose methods for interacting with the framework. These include:
+
+* `allMatches(Query)` - search for all objects matching the specified `Query`. +
++
++ Note that this, and other similar methods (eg `firstMatch(...)`, `uniqueMatch(...)`) will automatically flush the
+current transactoin.
+
+* `newTransientInstance(Class)` - to create a new instance of an object, with any services injected into it
+
+* `persistIfNotAlready(Object)` - to persist an object +
++
+In fact, the object is queued up to be persisted, and is only actually persisted either when the transaction commits, or
+when the transaction is flushed (typically when a query is performed).
+
+* `warnUser(String)` - generate a warning to the user
+
+* `getContainer()` - which returns the `DomainObjectContainer`
+
+Each of these methods simply delegates to an equivalent method in xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`].
+
+[TIP]
+====
+In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
index 1128ae6..cbdbcc1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
@@ -4,6 +4,15 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+This class is the superclass for all domain events that are raised by the framework when interacting with actions, properties or collections.
+Its immediate subclasses are:
+
+* xref:rg.adoc#_rg_classes_super_manpage-ActionDomainEvent[`ActionDomainEvent`]
+
+* xref:rg.adoc#_rg_classes_super_manpage-PropertyDomainEvent[`PropertyDomainEvent`]
+
+This class defines the `Phase` enum that is common to all domain events (hide/disable/validate/pre-execute/post-execute), and provides methods such as `veto(...)` by which subscribers can influence the interaction (eg hide a collection, disable a property, validate action arguments).
+
+It class also provides `get(...)` and `put(...)` methods that allow adhoc sharing of user data between different phases. One event instance is used for both the hide and disable phases, and a different event instance is shared between validate/pre-execute/post-execute.
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
index 1cb9017..6452c17 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
@@ -4,6 +4,11 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+
+This class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
+in convenience methods for managing the persistence lifecycle of the object instance.
+
+Each of these methods, eg `isPersistent(...)`, delegates to an equivalent method in
+xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`].
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc
deleted file mode 100644
index 733c16b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_rg_classes_super_manpage-AbstractDomainService]]
-= `AbstractDomainService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-NOTE: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
index 429ae76..7b044a4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
@@ -4,6 +4,12 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+
+This class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`]. Its
+intent was to be a convenience subclass for services acting as either a repository or a factory, however note that
+ all of the methods that it defines are now deprecated.
+
+Instead, indicate that a service is repository using the xref:rg.adoc#_rg_annotations_manpage-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
index 09ce823..daf67de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
@@ -4,6 +4,7 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
-
+This class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], adding
+in an implementation of `getId()` based upon the classes name.
+In practice there is little to gain from subclassing; simply inject xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
index aecd029..f7e718c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
@@ -4,6 +4,12 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+This class extends xref:rg.adoc#_rg_classes_super_manpage-AbstractContainedObject[`AbstractContainedObject`], also
+implementing the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface. In and of itself it provides no new behaviour.
+
+[TIP]
+====
+As an alternative, consider simply annotating the view model class with {@link org.apache.isis.applib.annotation.ViewModel}.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
index 4b18094..d5ed13b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
@@ -4,6 +4,17 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+Subclass of xref:rg.adoc#_rg_classes_super_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for actions.
+The class has a number of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* capture the arguments for each of the action's parameters
+
+* provide selected metadata about the action parameters from the metamodel (names, types)
+
+* link back to the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service's `Command` object
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
index bf6df17..f8953db 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
@@ -4,6 +4,18 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+
+Subclass of xref:rg.adoc#_rg_classes_super_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for collections.
+
+The class has a couple of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* indicate whether the interaction is to add or remove an object from the collection (or simply to indicate that the collection is being accessed/read)
+
+* capture the object reference being added or removed
+
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's collection.
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
index 5176546..1e240bc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
@@ -4,6 +4,18 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+The `FixtureScript` class is an abstract class defining an API to set up data within the object store, either for integration tests or while demoing/prototyping.
+
+The primary method that subclasses must implement is:
+
+[source,java]
+----
+protected abstract void execute(final ExecutionContext executionContext);
+----
+
+In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected
+domain services to set up data. The provided `ExecutionContext` is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).
+
+See the see the xref:ug.adoc#_ug_testing_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ug.adoc#_ug_testing_fixture-scripts_api-and-usage[fixture scripts' API and usage].
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
index fdf71f3..6ae5104 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
@@ -4,6 +4,9 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO - see also user guide's xref:ug.adoc#_ug_testing_fixture-scripts_api-and-usage[fixture scripts' API and usage], xref:rg.adoc#_rg_services-api_manpage-FixtureScriptsDefault[`FixtureScriptsDefault`] (fallback implementation) and xref:rg.adoc#_rg_services-spi_manpage-FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`].
+This abstract class is intended to allow a domain service that can execute xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`]s to be easily written.
+However, it has now been deprecated; instead we recommend that the xref:rg.adoc#_rg_services-spi_manpage-FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
+implemented instead. The framework will then automatically use.adoc#_rg_services-api_manpage-FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
+See the see the xref:ug.adoc#_ug_testing_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ug.adoc#_ug_testing_fixture-scripts_api-and-usage[fixture scripts' API and usage].
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
index ae26668..64961c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
@@ -4,6 +4,14 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+Subclass of xref:rg.adoc#_rg_classes_super_manpage-AbstractDomainEvent[`AbstractDomainEvent`] for properties.
+The class has a couple of responsibilities (in addition to those it inherits):
+
+* capture the target object being interacted with
+
+* capture the old and new values of the property
+
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's property.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
index 29c91f4..9b3e6c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
@@ -82,7 +82,7 @@ NOTE: TODO
.Isis Applib classes
-[cols="1,1,1", options="header"]
+[cols="1,1", options="header"]
|===
|Type
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/applib/src/main/java/org/apache/isis/applib/AbstractContainedObject.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/AbstractContainedObject.java b/core/applib/src/main/java/org/apache/isis/applib/AbstractContainedObject.java
index 66e3606..99536b1 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/AbstractContainedObject.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/AbstractContainedObject.java
@@ -20,8 +20,9 @@
package org.apache.isis.applib;
import java.util.List;
+
import com.google.common.base.Predicate;
-import org.apache.isis.applib.annotation.Aggregated;
+
import org.apache.isis.applib.annotation.Programmatic;
import org.apache.isis.applib.filter.Filter;
import org.apache.isis.applib.query.Query;
@@ -44,6 +45,8 @@ public abstract class AbstractContainedObject {
* this method, though the framework will also handle the case when
* the object is simply <i>new()</i>ed up. The benefits of using
* {@link #newTransientInstance(Class)} are:
+ * </p>
+ *
* <ul>
* <li>any services will be injected into the object immediately
* (otherwise they will not be injected until the framework
@@ -59,52 +62,49 @@ public abstract class AbstractContainedObject {
* The corollary is: if your code never uses <tt>default<i>Xxx</i>()</tt>
* supporting methods or the <tt>created()</tt> callback, then you can
* alternatively just <i>new()</i> up the object rather than call this
- * method.
-
+ * method.
+ *
* <p>
- * If the type is annotated with {@link Aggregated}, then as per
- * {@link #newAggregatedInstance(Object, Class)}. Otherwise will be an
- * aggregate root.
- *
- * @see #newAggregatedInstance(Object, Class)
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#newTransientInstance(Class)
*/
protected <T> T newTransientInstance(final Class<T> ofType) {
return getContainer().newTransientInstance(ofType);
}
/**
- * Create a new {@link ViewModel} of specified type, identified by memento.
- *
- * @param ofType
- * @param memento
- * @return
+ * Create a new {@link ViewModel} instance of the specified type, initializing with the specified memento.
+ *
+ * <p>
+ * Rather than use this constructor it is generally preferable to simply instantiate a
+ * class annotated with {@link org.apache.isis.applib.annotation.ViewModel annotation}.
+ * If services need injecting into it, use {@link DomainObjectContainer#injectServicesInto(Object)}.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#newViewModelInstance(Class, String)
*/
protected <T extends ViewModel> T newViewModelInstance(final Class<T> ofType, final String memento) {
return getContainer().newViewModelInstance(ofType, memento);
}
/**
- * Create an instance that will be persisted as part of this domain object
- * (ie this domain object is its parent in the aggregate).
- *
- * <p>
- * The type provided should be annotated with {@link Aggregated}.
- *
- * @see #newAggregatedInstance(Object, Class)
+ * @deprecated - not supported, will throw a RuntimeException
*/
+ @Deprecated
protected <T> T newAggregatedInstance(final Class<T> ofType) {
return newAggregatedInstance(this, ofType);
}
/**
- * Create an instance that will be persisted as part of specified paremt domain object
- * (ie that domain object will be its parent in the aggregate).
- *
- * <p>
- * The type provided should be annotated with {@link Aggregated}.
- *
- * @see #newAggregatedInstance(Class)
+ * @deprecated - not supported, will throw a RuntimeException
*/
+ @Deprecated
protected <T> T newAggregatedInstance(final Object parent, final Class<T> ofType) {
return getContainer().newAggregatedInstance(parent, ofType);
}
@@ -112,9 +112,30 @@ public abstract class AbstractContainedObject {
// //////////////////////////////////////
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns all the instances of the specified type (including subtypes).
+ * If the optional range parameters are used, the dataset returned starts
+ * from (0 based) index, and consists of only up to count items.
+ *
+ * <p>
+ * If there are no instances the list will be empty. This method creates a
+ * new {@link List} object each time it is called so the caller is free to
+ * use or modify the returned {@link List}, but the changes will not be
+ * reflected back to the repository.
+ * </p>
+ *
+ * <p>
+ * This method should only be called where the number of instances is known
+ * to be relatively low, unless the optional range parameters (2 longs) are
+ * specified. The range parameters are "start" and "count".
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#allInstances(Class, long...)
+ *
+ * @param range 2 longs, specifying 0-based start and count.
*/
protected <T> List<T> allInstances(final Class<T> ofType, long... range) {
return getContainer().allInstances(ofType, range);
@@ -123,20 +144,39 @@ public abstract class AbstractContainedObject {
// //////////////////////////////////////
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns all the instances of the specified type (including subtypes) that
+ * the predicate object accepts. If the optional range parameters are used, the
+ * dataset returned starts from (0 based) index, and consists of only up to
+ * count items.
+ *
+ * <p>
+ * If there are no instances the list will be empty. This method creates a
+ * new {@link List} object each time it is called so the caller is free to
+ * use or modify the returned {@link List}, but the changes will not be
+ * reflected back to the repository.
+ * </p>
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #allMatches(Query)} for production code.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#allMatches(Class, Predicate, long...)
+ * @see #allMatches(Query)
+ *
+ * @param range 2 longs, specifying 0-based start and count.
*/
+ @Programmatic
protected <T> List<T> allMatches(final Class<T> ofType, final Predicate<? super T> predicate, long... range) {
return getContainer().allMatches(ofType, predicate, range);
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
- * @see DomainObjectContainer#allMatches(Class, Filter, long...)
- *
- * @deprecated - use {@link #allMatches(Class, Predicate, long...)}
+ * @deprecated - use {@link #allMatches(Class, Predicate, long...)} or (better) {@link #allMatches(Query)} instead
*/
@Deprecated
protected <T> List<T> allMatches(final Class<T> ofType, final Filter<? super T> filter, long... range) {
@@ -144,26 +184,82 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns all the instances of the specified type (including subtypes) that
+ * match the given object: where any property that is set will be tested and
+ * properties that are not set will be ignored.
+ * If the optional range parameters are used, the dataset returned starts
+ * from (0 based) index, and consists of only up to count items.
+ *
+ * <p>
+ * If there are no instances the list will be empty. This method creates a
+ * new {@link List} object each time it is called so the caller is free to
+ * use or modify the returned {@link List}, but the changes will not be
+ * reflected back to the repository.
+ * </p>
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #allMatches(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#allMatches(Class, Object, long...)
+ *
+ * @param range 2 longs, specifying 0-based start and count.
*/
protected <T> List<T> allMatches(final Class<T> ofType, final T pattern, long... range) {
return getContainer().allMatches(ofType, pattern, range);
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns all the instances of the specified type (including subtypes) that
+ * have the given title.
+ * If the optional range parameters are used, the dataset returned starts
+ * from (0 based) index, and consists of only up to count items.
+ *
+ * <p>
+ * If there are no instances the list will be empty. This method creates a
+ * new {@link List} object each time it is called so the caller is free to
+ * use or modify the returned {@link List}, but the changes will not be
+ * reflected back to the repository.
+ * </p>
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #allMatches(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#allMatches(Class, String, long...)
+ *
+ * @param range 2 longs, specifying 0-based start and count.
*/
protected <T> List<T> allMatches(final Class<T> ofType, final String title, long... range) {
return getContainer().allMatches(ofType, title, range);
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns all the instances that match the given {@link Query}.
+ *
+ * <p>
+ * If there are no instances the list will be empty. This method creates a
+ * new {@link List} object each time it is called so the caller is free to
+ * use or modify the returned {@link List}, but the changes will not be
+ * reflected back to the repository.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#allMatches(Query)
*/
protected <T> List<T> allMatches(final Query<T> query) {
@@ -173,30 +269,47 @@ public abstract class AbstractContainedObject {
// //////////////////////////////////////
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns the first instance of the specified type (including subtypes)
+ * that matches the supplied {@link Predicate}, or <tt>null</tt> if none.
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #firstMatch(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#firstMatch(Class, Predicate)
- *
*/
protected <T> T firstMatch(final Class<T> ofType, final Predicate<T> predicate) {
return getContainer().firstMatch(ofType, predicate);
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
- * @see DomainObjectContainer#firstMatch(Class, Filter)
- *
* @deprecated - use {@link #firstMatch(Class, Predicate)}
*/
@Deprecated
protected <T> T firstMatch(final Class<T> ofType, final Filter<T> filter) {
return getContainer().firstMatch(ofType, filter);
}
-
+
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns the first instance of the specified type (including subtypes)
+ * that matches the supplied object as a pattern, or <tt>null</tt> if none.
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #firstMatch(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#firstMatch(Class, Object)
*/
protected <T> T firstMatch(final Class<T> ofType, final T pattern) {
@@ -204,8 +317,19 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns the first instance of the specified type (including subtypes)
+ * that matches the supplied title, or <tt>null</tt> if none.
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #firstMatch(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#firstMatch(Class, String)
*/
protected <T> T firstMatch(final Class<T> ofType, final String title) {
@@ -213,9 +337,19 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Returns the first instance that matches the supplied query, or <tt>null</tt> if none.
+ *
+ * <p>
+ * This method is the recommended way of querying for an instance when one or more may match. See also
+ * {@link #uniqueMatch(Query)}.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#firstMatch(Query)
+ * @see #uniqueMatch(Query)
*/
protected <T> T firstMatch(final Query<T> query) {
return getContainer().firstMatch(query);
@@ -225,8 +359,23 @@ public abstract class AbstractContainedObject {
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Find the only instance of the specified type (including subtypes) that
+ * has the specified title.
+ *
+ * <p>
+ * If no instance is found then <tt>null</tt> will be return, while if there
+ * is more that one instances a run-time exception will be thrown.
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #uniqueMatch(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#uniqueMatch(Class, Predicate)
*/
protected <T> T uniqueMatch(final Class<T> ofType, final Predicate<T> predicate) {
@@ -234,20 +383,31 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
- * @see DomainObjectContainer#uniqueMatch(Class, Filter)
- *
* @deprecated - use {@link #uniqueMatch(Class, Predicate)}
*/
@Deprecated
protected <T> T uniqueMatch(final Class<T> ofType, final Filter<T> filter) {
return getContainer().uniqueMatch(ofType, filter);
}
-
+
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Find the only instance of the specified type (including subtypes) that
+ * has the specified title.
+ *
+ * <p>
+ * If no instance is found then <tt>null</tt> will be returned, while if
+ * there is more that one instances a run-time exception will be thrown.
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #uniqueMatch(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#uniqueMatch(Class, String)
*/
protected <T> T uniqueMatch(final Class<T> ofType, final String title) {
@@ -255,8 +415,26 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Find the only instance of the patterned object type (including subtypes)
+ * that matches the set fields in the pattern object: where any property
+ * that is set will be tested and properties that are not set will be
+ * ignored.
+ *
+ * <p>
+ * If no instance is found then null will be return, while if there is more
+ * that one instances a run-time exception will be thrown.
+ * </p>
+ *
+ * <p>
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #uniqueMatch(Query)} for production code.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see DomainObjectContainer#uniqueMatch(Class, Object)
*/
protected <T> T uniqueMatch(final Class<T> ofType, final T pattern) {
@@ -264,8 +442,23 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience method that delegates to {@link DomainObjectContainer}.
- *
+ * Find the only instance that matches the provided query.
+ *
+ * <p>
+ * If no instance is found then null will be return, while if there is more
+ * that one instances a run-time exception will be thrown.
+ * </p>
+ *
+ * <p>
+ * This method is the recommended way of querying for (precisely) one instance. See also {@link #firstMatch(Query)}
+ * for less strict querying.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see #firstMatch(Query)
* @see DomainObjectContainer#uniqueMatch(Query)
*/
protected <T> T uniqueMatch(final Query<T> query) {
@@ -275,8 +468,14 @@ public abstract class AbstractContainedObject {
// //////////////////////////////////////
/**
- * Convenience methods that delegates to {@link DomainObjectContainer}.
- *
+ * Whether the object is in a valid state, that is that none of the
+ * validation of properties, collections and object-level is vetoing.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see #validate(Object)
* @see DomainObjectContainer#isValid(Object)
*/
protected boolean isValid(final Object domainObject) {
@@ -284,8 +483,18 @@ public abstract class AbstractContainedObject {
}
/**
- * Convenience methods that delegates to {@link DomainObjectContainer}.
- *
+ * The reason, if any why the object is in a invalid state
+ *
+ * <p>
+ * Checks the validation of all of the properties, collections and
+ * object-level.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see #isValid(Object)
* @see DomainObjectContainer#validate(Object)
*/
protected String validate(final Object domainObject) {
@@ -295,29 +504,44 @@ public abstract class AbstractContainedObject {
// //////////////////////////////////////
/**
- * Determines if the specified object is persistent (that it is stored
- * permanently outside of the virtual machine).
+ * Determines if the specified object is persistent (that it is stored permanently outside of the virtual machine
+ * in the object store).
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#isPersistent(Object)
*/
protected boolean isPersistent(final Object domainObject) {
return getContainer().isPersistent(domainObject);
}
/**
- * Persist the specified transient object.
- *
+ * Queues up a request to persist this object to the object store. The object is persisted either
+ * when the transaction is committed, or when it is flushed. Flushing is performed either implicitly whenever a subsequent query is run,
+ * or can be performed explicitly using {@link DomainObjectContainer#flush()}.
+ *
* <p>
* It is recommended that the object be initially instantiated using
* {@link #newTransientInstance(Class)}. However, the framework will also
* handle the case when the object is simply <i>new()</i>ed up. See
* {@link #newTransientInstance(Class)} for more information.
- *
+ * </p>
+ *
* <p>
- * Throws an exception if object is already persistent, or if the object
- * is not yet known to the framework.
- *
+ * This method will throw an exception if the object {@link #isPersistent(Object) is persistent} already. For this reason
+ * {@link #persistIfNotAlready(Object)} is generally preferred.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
* @see #newTransientInstance(Class)
* @see #isPersistent(Object)
* @see #persistIfNotAlready(Object)
+ * @see DomainObjectContainer#persist(Object)
*/
protected <T> T persist(final T transientDomainObject) {
getContainer().persist(transientDomainObject);
@@ -325,17 +549,24 @@ public abstract class AbstractContainedObject {
}
/**
- * Persist the specified object (or do nothing if already persistent).
- *
+ * Queues up a request to persist this object to the object store (as per {@link #persist(Object)}) (or do
+ * nothing if the object is already {@link #isPersistent(Object) persistent}).
+ *
* <p>
* It is recommended that the object be initially instantiated using
* {@link #newTransientInstance(Class)}. However, the framework will also
* handle the case when the object is simply <i>new()</i>ed up. See
* {@link #newTransientInstance(Class)} for more information.
+ * </p>
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
*
* @see #newTransientInstance(Class)
* @see #isPersistent(Object)
* @see #persist(Object)
+ * @see {@link DomainObjectContainer#persistIfNotAlready(Object)}
*/
protected <T> T persistIfNotAlready(final T domainObject) {
getContainer().persistIfNotAlready(domainObject);
@@ -344,6 +575,12 @@ public abstract class AbstractContainedObject {
/**
* Delete the provided object from the persistent object store.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#remove(Object)
*/
protected <T> T remove(final T persistentDomainObject) {
getContainer().remove(persistentDomainObject);
@@ -352,6 +589,12 @@ public abstract class AbstractContainedObject {
/**
* Delete the provided object from the persistent object store.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#removeIfNotAlready(Object)
*/
protected <T> T removeIfNotAlready(final T persistentDomainObject) {
getContainer().removeIfNotAlready(persistentDomainObject);
@@ -362,13 +605,25 @@ public abstract class AbstractContainedObject {
/**
* Display the specified message to the user, in a non-intrusive fashion.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#informUser(String)
*/
protected void informUser(final String message) {
getContainer().informUser(message);
}
/**
- * Display the specified message to the user, in a non-intrusive fashion.
+ * Display the specified i18n message to the user, in a non-intrusive fashion.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#informUser(TranslatableString, Class, String)
*/
protected void informUser(TranslatableString message, final Class<?> contextClass, final String contextMethod) {
getContainer().informUser(message, contextClass, contextMethod);
@@ -377,12 +632,27 @@ public abstract class AbstractContainedObject {
/**
* Display the specified message as a warning to the user, in a more visible
* fashion, but without requiring explicit acknowledgement.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#warnUser(String)
*/
protected void warnUser(final String message) {
getContainer().warnUser(message);
}
-
+ /**
+ * Display the specified i18n message as a warning to the user, in a more visible
+ * fashion, but without requiring explicit acknowledgement.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#warnUser(TranslatableString, Class, String)
+ */
protected void warnUser(TranslatableString message, final Class<?> contextClass, final String contextMethod) {
getContainer().warnUser(message, contextClass, contextMethod);
}
@@ -390,17 +660,42 @@ public abstract class AbstractContainedObject {
/**
* Display the specified message as an error to the user, ensuring that it
* is acknowledged.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#raiseError(String)
*/
protected void raiseError(final String message) {
getContainer().raiseError(message);
}
+ /**
+ * Display the specified i18n message as an error to the user, ensuring that it
+ * is acknowledged.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#raiseError(TranslatableString, Class, String)
+ */
protected String raiseError(TranslatableString message, final Class<?> contextClass, final String contextMethod) {
return getContainer().raiseError(message, contextClass, contextMethod);
}
// //////////////////////////////////////
+ /**
+ * Get the details about the current user.
+ *
+ * <p>
+ * The method simply delegates to the {@link DomainObjectContainer}.
+ * </p>
+ *
+ * @see DomainObjectContainer#getUser()
+ */
protected UserMemento getUser() {
return getContainer().getUser();
}
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/applib/src/main/java/org/apache/isis/applib/AbstractDomainObject.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/AbstractDomainObject.java b/core/applib/src/main/java/org/apache/isis/applib/AbstractDomainObject.java
index 0d25e4c..41f1284 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/AbstractDomainObject.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/AbstractDomainObject.java
@@ -19,7 +19,7 @@
package org.apache.isis.applib;
-import org.apache.isis.applib.annotation.Hidden;
+import org.apache.isis.applib.annotation.Programmatic;
/**
* Convenience super class for all domain objects that wish to interact with the
@@ -33,88 +33,112 @@ import org.apache.isis.applib.annotation.Hidden;
*/
public abstract class AbstractDomainObject extends AbstractContainedObject {
- // {{ resolve, objectChanged
+ //region > resolve, objectChanged
+
/**
- * Resolve this object, populating references to other objects.
+ * Re-initialises the fields of an object, using the
+ * JDO {@link javax.jdo.PersistenceManager#refresh(Object) refresh} API.
+ *
+ * <p>
+ * Previously this method was provided for manual control of lazy loading; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated - equivalent to {@link org.apache.isis.applib.services.jdosupport.IsisJdoSupport#refresh(Object)}.
*/
- @Hidden
+ @Programmatic
+ @Deprecated
protected void resolve() {
getContainer().resolve(this);
}
/**
- * Resolve this object if the referenced object is still unknown.
+ * Provided that the <tt>field</tt> parameter is <tt>null</tt>, re-initialises the fields of an object, using the
+ * JDO {@link javax.jdo.PersistenceManager#refresh(Object) refresh} API.
+ *
+ * <p>
+ * Previously this method was provided for manual control of lazy loading; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated - equivalent to {@link org.apache.isis.applib.services.jdosupport.IsisJdoSupport#refresh(Object)}.
*/
- @Hidden
+ @Programmatic
+ @Deprecated
protected void resolve(final Object referencedObject) {
getContainer().resolve(this, referencedObject);
}
/**
- * Notifies the container that this object has changed, so that it can be
- * persisted.
+ * This method does nothing (is a no-op).
+ *
+ * <p>
+ * Previous this method was provided for manual control of object dirtyng; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated
*/
- @Hidden
+ @Programmatic
+ @Deprecated
protected void objectChanged() {
getContainer().objectChanged(this);
}
- // }}
+ //endregion
- // {{ isPersistent, makePersistent (overloads)
+ //region > isPersistent, makePersistent (overloads)
/**
- * Whether this object is persistent.
- *
- * @deprecated - instead use {@link #isPersistent(Object)}.
+ * Deprecated, recommend use {@link #isPersistent(Object)} instead.
+ *
+ * @see #isPersistent(Object)
+ *
+ * @deprecated - instead recommend that {@link #isPersistent(Object)} or simply {@link DomainObjectContainer#isPersistent(Object)} be used instead.
*/
@Deprecated
- @Hidden
+ @Programmatic
protected boolean isPersistent() {
return isPersistent(this);
}
/**
- * Save this object to the persistent object store.
- *
- * <p>
- * If the object {@link #isPersistent(Object) is persistent} already, then
- * will throw an exception.
- *
- * @see #persistIfNotAlready(Object)
- *
+ * Deprecated, has been renamed to {@link #persist(Object)}.
+ *
+ * @see #persist(Object)
+ *
* @deprecated - instead use {@link #persist(Object)}.
*/
@Deprecated
- @Hidden
+ @Programmatic
protected void makePersistent() {
persist(this);
}
/**
- * Saves the object, but only if not already {@link #isPersistent(Object)
- * persistent}.
- *
- * @see #isPersistent(Object)
- * @see #persist(Object)
+ * Deprecated, has been renamed to {@link #persistIfNotAlready(Object)}.
+ *
+ * @see #persistIfNotAlready(Object)
*
* @deprecated - instead use {@link #persistIfNotAlready(Object)}.
*/
@Deprecated
- @Hidden
+ @Programmatic
protected void makePersistentIfNotAlready() {
persistIfNotAlready(this);
}
/**
- * Delete this object from the persistent object store.
+ * Deprecated, has been renamed to {@link #remove(Object)}.
+ *
+ * @see #remove(Object).
*
* @deprecated - instead use {@link #remove(Object)}.
*/
@Deprecated
- @Hidden
+ @Programmatic
protected void disposeInstance() {
remove(this);
}
- // }}
+ //endregion
}
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/applib/src/main/java/org/apache/isis/applib/AbstractFactoryAndRepository.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/AbstractFactoryAndRepository.java b/core/applib/src/main/java/org/apache/isis/applib/AbstractFactoryAndRepository.java
index bbe3162..fe7486c 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/AbstractFactoryAndRepository.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/AbstractFactoryAndRepository.java
@@ -19,32 +19,29 @@
package org.apache.isis.applib;
+/**
+ * @deprecated - annotate with DomainService#repositoryFor()} instead.
+ */
+@Deprecated
public abstract class AbstractFactoryAndRepository extends AbstractService {
- // {{ newPersistenceInstance, newInstance
/**
- * Returns a new instance of the specified class that will have been
- * persisted.
- *
- * <p>
- * This method isn't quite deprecated, but generally consider using
- * {@link #newTransientInstance(Class)} instead.
+ * @see DomainObjectContainer#newPersistentInstance(Class)
+ * @deprecated - see {@link DomainObjectContainer#newPersistentInstance(Class)} for rationale.
*/
+ @Deprecated
protected <T> T newPersistentInstance(final Class<T> ofClass) {
return getContainer().newPersistentInstance(ofClass);
}
/**
- * Returns a new instance of the specified class that has the sane persisted
- * state as the specified object.
- *
- * <p>
- * This method isn't quite deprecated, but generally consider using
- * {@link #newTransientInstance(Class)} instead.
+ * @see DomainObjectContainer#newInstance(Class, Object)
+ *
+ * @deprecated - this method supports a rare use case, causing unnecessary interface bloat for very little gain.
*/
+ @Deprecated
protected <T> T newInstance(final Class<T> ofClass, final Object object) {
return getContainer().newInstance(ofClass, object);
}
- // }}
}
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/applib/src/main/java/org/apache/isis/applib/DomainObjectContainer.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/DomainObjectContainer.java b/core/applib/src/main/java/org/apache/isis/applib/DomainObjectContainer.java
index c347593..29f7c64 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/DomainObjectContainer.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/DomainObjectContainer.java
@@ -20,9 +20,10 @@
package org.apache.isis.applib;
import java.util.List;
+
import com.google.common.base.Function;
import com.google.common.base.Predicate;
-import org.apache.isis.applib.annotation.Aggregated;
+
import org.apache.isis.applib.annotation.Programmatic;
import org.apache.isis.applib.filter.Filter;
import org.apache.isis.applib.query.Query;
@@ -50,48 +51,43 @@ public interface DomainObjectContainer {
//region > resolve, objectChanged
/**
- * Ensure that the specified object is completely loaded into memory.
- *
- * <p>
- * This forces the lazy loading mechanism to load the object if it is not
- * already loaded.
- *
+ * Re-initialises the fields of an object, using the
+ * JDO {@link javax.jdo.PersistenceManager#refresh(Object) refresh} API.
+ *
* <p>
- * This method has been deprecated because lazy loading is now typically performed
- * by the framework, rather than by application code.
- *
- * @deprecated
+ * Previously this method was provided for manual control of lazy loading; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated - equivalent to {@link org.apache.isis.applib.services.jdosupport.IsisJdoSupport#refresh(Object)}.
*/
@Programmatic
@Deprecated
void resolve(Object domainObject);
/**
- * Ensure that the specified object is completely loaded into memory, though
- * only if the supplied field reference is <tt>null</tt>.
- *
- * <p>
- * This forces the lazy loading mechanism to load the object if it is not
- * already loaded.
- *
+ * Provided that the <tt>field</tt> parameter is <tt>null</tt>, re-initialises the fields of an object, using the
+ * JDO {@link javax.jdo.PersistenceManager#refresh(Object) refresh} API.
+ *
* <p>
- * This method has been deprecated because lazy loading is now typically performed
- * by the framework, rather than by application code.
- *
- * @deprecated
+ * Previously this method was provided for manual control of lazy loading; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated - equivalent to {@link org.apache.isis.applib.services.jdosupport.IsisJdoSupport#refresh(Object)}.
*/
@Programmatic
@Deprecated
void resolve(Object domainObject, Object field);
/**
- * Flags that the specified object's state has changed and its changes need
- * to be saved.
- *
+ * This method does nothing (is a no-op).
+ *
* <p>
- * This method has been deprecated because object dirtying is now typically performed
- * by the framework, rather than by application code.
- *
+ * Previous this method was provided for manual control of object dirtyng; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
* @deprecated
*/
@Programmatic
@@ -141,6 +137,8 @@ public interface DomainObjectContainer {
* this method, though the framework will also handle the case when
* the object is simply <i>new()</i>ed up. The benefits of using
* {@link #newTransientInstance(Class)} are:
+ * </p>
+ *
* <ul>
* <li>any services will be injected into the object immediately
* (otherwise they will not be injected until the framework
@@ -156,23 +154,18 @@ public interface DomainObjectContainer {
* The corollary is: if your code never uses <tt>default<i>Xxx</i>()</tt>
* supporting methods or the <tt>created()</tt> callback, then you can
* alternatively just <i>new()</i> up the object rather than call this
- * method.
+ * method.
+ * </p>
- * <p>
- * If the type is annotated with {@link Aggregated}, then as per
- * {@link #newAggregatedInstance(Object, Class)}. Otherwise will be an
- * aggregate root.
- *
+ *
* @see #newPersistentInstance(Class)
- * @see #newAggregatedInstance(Object, Class)
*/
@Programmatic
<T> T newTransientInstance(final Class<T> ofType);
/**
- * Create a new instance of the specified view model class, initializing with the
- * specified memento.
+ * Create a new {@link ViewModel} instance of the specified type, initializing with the specified memento.
*
* <p>
* Rather than use this constructor it is generally preferable to simply instantiate a
@@ -191,18 +184,14 @@ public interface DomainObjectContainer {
<T> T newAggregatedInstance(Object parent, Class<T> ofType);
/**
- * Returns a new instance of the specified class that will have been
+ * (Deprecated) returns a new instance of the specified class that will have been
* persisted.
- *
- * <p>
- * This method has been deprecated because in almost all cases the
- * workflow is to {@link #newTransientInstance(Class)}, populate the object
- * (eg with the arguments to an action) and then to
+ *
+ * @deprecated - in almost all cases the workflow is to {@link #newTransientInstance(Class)}, populate the object
+ * (eg with the arguments to an action) and then to
* {@link #persist(Object) persist) the object. It is exceptionally rare for
* an object to be created, and with no further data required - be in a state
* to be persisted immediately.
- *
- * @deprecated
*/
@Programmatic
@Deprecated
@@ -215,6 +204,7 @@ public interface DomainObjectContainer {
* <p>
* This method has been deprecated because it is a rare use case, causing
* unnecessary interface bloat for very little gain.
+ * <p></p>
*
* @deprecated
*/
@@ -255,7 +245,8 @@ public interface DomainObjectContainer {
* <p>
* Checks the validation of all of the properties, collections and
* object-level.
- *
+ * </p>
+ *
* @see #isValid(Object)
*/
@Programmatic
@@ -273,8 +264,8 @@ public interface DomainObjectContainer {
//region > isPersistent, persist, remove
/**
- * Determines if the specified object is persistent (that it is stored
- * permanently outside of the virtual machine).
+ * Determines if the specified object is persistent (that it is stored permanently outside of the virtual machine
+ * in the object store).
*/
@Programmatic
boolean isPersistent(Object domainObject);
@@ -459,17 +450,20 @@ public interface DomainObjectContainer {
/**
* Returns all the instances of the specified type (including subtypes).
* If the optional range parameters are used, the dataset returned starts
- * from (0 based) index, and consists of only up to count items.
+ * from (0 based) index, and consists of only up to count items.
+ *
* <p>
* If there are no instances the list will be empty. This method creates a
* new {@link List} object each time it is called so the caller is free to
* use or modify the returned {@link List}, but the changes will not be
* reflected back to the repository.
+ * </p>
*
* <p>
* This method should only be called where the number of instances is known
* to be relatively low, unless the optional range parameters (2 longs) are
* specified. The range parameters are "start" and "count".
+ * </p>
*
* @param range 2 longs, specifying 0-based start and count.
*/
@@ -487,35 +481,23 @@ public interface DomainObjectContainer {
* new {@link List} object each time it is called so the caller is free to
* use or modify the returned {@link List}, but the changes will not be
* reflected back to the repository.
+ * </p>
*
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #allMatches(Query)} for production code.
- *
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #allMatches(Query)} for production code.
+ * </p>
+ *
+ * @see #allMatches(Class, Predicate, long...)
+ *
* @param range 2 longs, specifying 0-based start and count.
*/
@Programmatic
<T> List<T> allMatches(final Class<T> ofType, final Predicate<? super T> predicate, long... range);
/**
- * Returns all the instances of the specified type (including subtypes) that
- * the filter object accepts. If the optional range parameters are used, the
- * dataset returned starts from (0 based) index, and consists of only up to
- * count items.
- *
- * <p>
- * If there are no instances the list will be empty. This method creates a
- * new {@link List} object each time it is called so the caller is free to
- * use or modify the returned {@link List}, but the changes will not be
- * reflected back to the repository.
- *
- * <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #allMatches(Query)} for production code.
- *
- * @param range 2 longs, specifying 0-based start and count.
- *
- * @deprecated - use {@link #allMatches(Class, Predicate, long...)} instead.
+ * @deprecated - use {@link #allMatches(Class, Predicate, long...)} or (better) {@link #allMatches(Query)} instead
*/
@Programmatic
@Deprecated
@@ -532,11 +514,14 @@ public interface DomainObjectContainer {
* new {@link List} object each time it is called so the caller is free to
* use or modify the returned {@link List}, but the changes will not be
* reflected back to the repository.
- *
+ * </p>
+ *
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #allMatches(Query)} for production code.
- *
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #allMatches(Query)} for production code.
+ * </p>
+ *
* @param range 2 longs, specifying 0-based start and count.
*/
@Programmatic
@@ -554,11 +539,14 @@ public interface DomainObjectContainer {
* new {@link List} object each time it is called so the caller is free to
* use or modify the returned {@link List}, but the changes will not be
* reflected back to the repository.
- *
+ * </p>
+ *
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #allMatches(Query, long...)} for production code.
- *
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #allMatches(Query)} for production code.
+ * </p>
+ *
* @param range 2 longs, specifying 0-based start and count.
*/
@Programmatic
@@ -566,12 +554,17 @@ public interface DomainObjectContainer {
/**
* Returns all the instances that match the given {@link Query}.
- *
+ *
* <p>
* If there are no instances the list will be empty. This method creates a
* new {@link List} object each time it is called so the caller is free to
* use or modify the returned {@link List}, but the changes will not be
* reflected back to the repository.
+ * </p>
+ *
+ * <p>
+ * This method is the recommended way of querying for multiple instances.
+ * </p>
*/
@Programmatic
<T> List<T> allMatches(Query<T> query);
@@ -583,20 +576,15 @@ public interface DomainObjectContainer {
* that matches the supplied {@link Predicate}, or <tt>null</tt> if none.
*
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #firstMatch(Query)} for production code.
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #firstMatch(Query)} for production code.
+ * </p>
*/
@Programmatic
<T> T firstMatch(final Class<T> ofType, final Predicate<T> predicate);
/**
- * Returns the first instance of the specified type (including subtypes)
- * that matches the supplied {@link Filter}, or <tt>null</tt> if none.
- *
- * <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #firstMatch(Query)} for production code.
- *
* @deprecated - use {@link #firstMatch(Class, Predicate)}
*/
@Programmatic
@@ -606,10 +594,12 @@ public interface DomainObjectContainer {
/**
* Returns the first instance of the specified type (including subtypes)
* that matches the supplied title, or <tt>null</tt> if none.
- *
+ *
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #firstMatch(Query)} for production code.
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #firstMatch(Query)} for production code.
+ * </p>
*/
@Programmatic
<T> T firstMatch(Class<T> ofType, String title);
@@ -617,17 +607,25 @@ public interface DomainObjectContainer {
/**
* Returns the first instance of the specified type (including subtypes)
* that matches the supplied object as a pattern, or <tt>null</tt> if none.
- *
+ *
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #firstMatch(Query)} for production code.
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #firstMatch(Query)} for production code.
+ * </p>
*/
@Programmatic
<T> T firstMatch(Class<T> ofType, T pattern);
/**
- * Returns the first instance that matches the supplied query, or
- * <tt>null</tt> if none.
+ * Returns the first instance that matches the supplied query, or <tt>null</tt> if none.
+ *
+ * <p>
+ * This method is the recommended way of querying for an instance when one or more may match. See also
+ * {@link #uniqueMatch(Query)}.
+ * </p>
+ *
+ * @see #uniqueMatch(Query)
*/
@Programmatic
<T> T firstMatch(Query<T> query);
@@ -643,24 +641,15 @@ public interface DomainObjectContainer {
* is more that one instances a run-time exception will be thrown.
*
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #uniqueMatch(Query)} for production code.
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #uniqueMatch(Query)} for production code.
+ * </p>
*/
@Programmatic
<T> T uniqueMatch(final Class<T> ofType, final Predicate<T> predicate);
/**
- * Find the only instance of the specified type (including subtypes) that
- * has the specified title.
- *
- * <p>
- * If no instance is found then <tt>null</tt> will be return, while if there
- * is more that one instances a run-time exception will be thrown.
- *
- * <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #uniqueMatch(Query)} for production code.
- *
* @deprecated - use {@link #uniqueMatch(Class, Predicate)}
*/
@Programmatic
@@ -676,8 +665,10 @@ public interface DomainObjectContainer {
* there is more that one instances a run-time exception will be thrown.
*
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #uniqueMatch(Query)} for production code.
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #uniqueMatch(Query)} for production code.
+ * </p>
*/
@Programmatic
<T> T uniqueMatch(Class<T> ofType, String title);
@@ -691,10 +682,13 @@ public interface DomainObjectContainer {
* <p>
* If no instance is found then null will be return, while if there is more
* that one instances a run-time exception will be thrown.
- *
+ * </p>
+ *
* <p>
- * This method is useful during exploration/prototyping, but you may want to
- * use {@link #uniqueMatch(Query)} for production code.
+ * This method is useful during exploration/prototyping, but - because the filtering is performed client-side -
+ * this method is only really suitable for initial development/prototyping, or for classes with very few
+ * instances. Use {@link #uniqueMatch(Query)} for production code.
+ * </p>
*/
@Programmatic
<T> T uniqueMatch(Class<T> ofType, T pattern);
@@ -705,6 +699,14 @@ public interface DomainObjectContainer {
* <p>
* If no instance is found then null will be return, while if there is more
* that one instances a run-time exception will be thrown.
+ * </p>
+ *
+ * <p>
+ * This method is the recommended way of querying for (precisely) one instance. See also {@link #firstMatch(Query)}
+ * for less strict querying.
+ * </p>
+ *
+ * @see #firstMatch(Query)
*/
@Programmatic
<T> T uniqueMatch(Query<T> query);
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScript.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScript.java b/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScript.java
index 35a5661..56f6ed4 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScript.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScript.java
@@ -26,10 +26,13 @@ import java.math.BigInteger;
import java.util.Collections;
import java.util.List;
import java.util.Map;
+
import com.google.common.base.Strings;
import com.google.common.collect.Maps;
+
import org.joda.time.LocalDate;
import org.joda.time.LocalDateTime;
+
import org.apache.isis.applib.AbstractViewModel;
import org.apache.isis.applib.DomainObjectContainer;
import org.apache.isis.applib.annotation.Programmatic;
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScripts.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScripts.java b/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScripts.java
index 600faeb..7089de0 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScripts.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/fixturescripts/FixtureScripts.java
@@ -49,6 +49,10 @@ import org.apache.isis.applib.services.memento.MementoService;
import org.apache.isis.applib.services.memento.MementoService.Memento;
import org.apache.isis.applib.util.ObjectContracts;
+/**
+ * @deprecated - instead implement {@link org.apache.isis.applib.services.fixturespec.FixtureScriptsSpecificationProvider}.
+ */
+@Deprecated
public abstract class FixtureScripts extends AbstractService {
http://git-wip-us.apache.org/repos/asf/isis/blob/ecc32623/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/container/DomainObjectContainerDefault.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/container/DomainObjectContainerDefault.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/container/DomainObjectContainerDefault.java
index 9366510..f9f23ed 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/container/DomainObjectContainerDefault.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/container/DomainObjectContainerDefault.java
@@ -233,20 +233,36 @@ public class DomainObjectContainerDefault
//region > resolve, objectChanged (deprecated)
/**
- * Deprecated because all supported objectstores provide lazy loading and dirty object tracking.
+ * Re-initialises the fields of an object, using the
+ * JDO {@link javax.jdo.PersistenceManager#refresh(Object) refresh} API.
+ *
+ * <p>
+ * Previously this method was provided for manual control of lazy loading; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated - equivalent to {@link org.apache.isis.applib.services.jdosupport.IsisJdoSupport#refresh(Object)}.
*/
- @Deprecated
@Programmatic
+ @Deprecated
@Override
public void resolve(final Object parent) {
getPersistenceSessionService().resolve(unwrapped(parent));
}
/**
- * Deprecated because all supported objectstores provide lazy loading and dirty object tracking.
+ * Provided that the <tt>field</tt> parameter is <tt>null</tt>, re-initialises the fields of an object, using the
+ * JDO {@link javax.jdo.PersistenceManager#refresh(Object) refresh} API.
+ *
+ * <p>
+ * Previously this method was provided for manual control of lazy loading; with the JDO/DataNucleus objectstore
+ * that original functionality is performed automatically by the framework.
+ * </p>
+ *
+ * @deprecated - equivalent to {@link org.apache.isis.applib.services.jdosupport.IsisJdoSupport#refresh(Object)}.
*/
- @Deprecated
@Programmatic
+ @Deprecated
@Override
public void resolve(final Object parent, final Object field) {
getPersistenceSessionService().resolve(unwrapped(parent), field);
[2/2] isis git commit: ISIS-1007: updates to docs
Posted by da...@apache.org.
ISIS-1007: updates to docs
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/7ecb9485
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/7ecb9485
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/7ecb9485
Branch: refs/heads/master
Commit: 7ecb94853cb564f6f4909ff47a69a63a566127f9
Parents: ecc3262
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Oct 7 08:20:20 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Oct 7 08:20:20 2015 +0100
----------------------------------------------------------------------
.../guides/_rg_annotations_manpage-Action.adoc | 14 ++++++++++++--
.../guides/_rg_services-api_manpage-Scratchpad.adoc | 6 ++++--
.../_ug_restfulobjects-viewer_hints-and-tips.adoc | 10 +++++++---
.../_ug_wicket-viewer_features_bookmarked-pages.adoc | 5 +++--
4 files changed, 26 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/7ecb9485/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
index 0079b56..13844d9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
@@ -73,9 +73,13 @@ Currently this is only supported for no-arg actions.
|whether the action is only available in prototyping mode, or whether it is available also in production mode.
|xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`semantics()`]
-|`SAFE_AND_REQUEST_CACHEABLE`, `SAFE`, `IDEMPOTENT`, `NON_IDEMPOTENT` +
+|`SAFE_AND_REQUEST_CACHEABLE`, `SAFE`, +
+`IDEMPOTENT`, `IDEMPOTENT_ARE_YOU_SURE` +
+`NON_IDEMPOTENT`, `NON_IDEMPOTENT_ARE_YOU_SURE` + +
(`NON_IDEMPOTENT`)
-|the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change; if not whether the results can be cached for the remainder of the request)
+|the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change; if not whether the results can be cached for the remainder of the request).
+
+The `...ARE_YOU_SURE` variants (1.10.0-SNAPSHOT) cause a confirmation dialog to be displayed in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer].
|xref:rg.adoc#_rg_annotations_manpage-Action_typeOf[`typeOf()`]
|(none)
@@ -118,6 +122,12 @@ public class ToDoItem {
+[NOTE]
+====
+Currently are you sure semantics (1.10.0-SNAPSHOT) only work for actions that take one or more parameters (that is, generate a dialog).
+====
+
+
include::_rg_annotations_manpage-Action_command.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/7ecb9485/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
index b4ce0b4..6ff24de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
@@ -43,8 +43,10 @@ For example, the Isis addons example https://github.com/isisaddons/isis-app-todo
[source,java]
----
-@ActionSemantics(Of.SAFE)
-@Bulk(AppliesTo.BULK_ONLY)
+@Action(
+ semantics=SemanticsOf.SAFE,
+ invokeOn=InvokeOn.COLLECTION_ONLY
+)
public BigDecimal totalCost() {
BigDecimal total = (BigDecimal) scratchpad.get("runningTotal");
if(getCost() != null) {
http://git-wip-us.apache.org/repos/asf/isis/blob/7ecb9485/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
index b321d1a..52a74cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
@@ -34,9 +34,13 @@ Suppose you have a `CustomerService` providing a `findCustomer` action:
[source,java]
----
public class CustomerService {
- public String id() { return "customers"; }
- @ActionSemantics(Of.SAFE)
- public Customer findCustomer(@Named("customerName") String customerName) { ... }
+ public String id() { return "customers"; }
+ @Action(semantics=SemanticsOf.SAFE)
+ public Customer findCustomer(
+ @ParameterLayout(named="customerName")
+ final String customerName) {
+ ...
+ }
}
----
http://git-wip-us.apache.org/repos/asf/isis/blob/7ecb9485/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
index 530f4df..76e2b28 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
@@ -64,11 +64,12 @@ To indicate that a safe (query only) action is bookmarkable, use the xref:rg.ado
[source,java]
----
public class ToDoItem ... {
- ...
+ @Action(
+ semantics=SemanticsOf.SAFE
+ )
@ActionLayout(
bookmarking=BookmarkPolicy.AS_ROOT
)
- @ActionSemantics(Of.SAFE)
public List<ToDoItem> notYetComplete() { ... }
...
}