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 2017/04/20 08:13:00 UTC
[51/58] [abbrv] isis git commit: wip - ugfun.adoc , crud
wip - ugfun.adoc , crud
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/842c5b43
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/842c5b43
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/842c5b43
Branch: refs/heads/wip
Commit: 842c5b43d700ef1fe9f0b55f8cab41fe25ca5c7a
Parents: 2693c5c
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 21:01:45 2017 +0200
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100
----------------------------------------------------------------------
.../main/asciidoc/guides/ugfun/_ugfun_crud.adoc | 2 ++
.../guides/ugfun/_ugfun_crud_deleting.adoc | 18 ++++++++++++++
.../guides/ugfun/_ugfun_crud_finding.adoc | 6 +++++
.../guides/ugfun/_ugfun_crud_instantiating.adoc | 2 +-
.../guides/ugfun/_ugfun_crud_persisting.adoc | 14 +++++++++++
.../guides/ugfun/_ugfun_crud_updating.adoc | 25 ++++++++++++++++++++
6 files changed, 66 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
index add909f..a34e7d3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
@@ -22,6 +22,8 @@ include::_ugfun_crud_persisting.adoc[leveloffset=+1]
include::_ugfun_crud_finding.adoc[leveloffset=+1]
+include::_ugfun_crud_updating.adoc[leveloffset=+1]
+
include::_ugfun_crud_deleting.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
index edb0257..015edf4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
@@ -4,10 +4,28 @@
:_basedir: ../../
:_imagesdir: images/
+Domain entities can be deleted using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`].
+For example:
+[source,java]
+----
+Customer customer = ...
+repositoryService.remove(customer);
+----
+It's worth being aware that (as for persisting new entities) the framework does _not_ eagerly delete the object.
+Rather, it queues up an internal command structure representing the object deletion request.
+This is then executed either at the end of the transaction, or if a xref:../ugfun/ugfun.adoc#_ugfun_crud_finding[query is run], or if the internal queue is manually flushed using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]'s `flush()` method.
+Alternatively, you can use:
+[source,java]
+----
+repositoryService.removeAndFlush(customer);
+----
+to eagerly perform the object deletion from the database.
+
+When an object is deleted the framework will emit `ObjectRemovingEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event].
http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
index 9b542ae..971245b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
@@ -53,6 +53,12 @@ public class CustomerRepository {
<3> Corresponds to the `@Query#name()` attribute
<4> Corresponds to the `:name` parameter in the query JDOQL string
+Whenever a query is submitted, the framework will automatically "flush" any pending changes.
+This ensures that the database query runs against an up-to-date table so that all matching instances (with respect to the current transaction) are correctly retrieved.
+
+
+When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event].
+
== Using DataNucleus type-safe queries
http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
index 7eae5c8..1ed757d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
@@ -21,7 +21,7 @@ or
Dashboard dashboardVM = factoryService.instantiate(Dashboard.class);
----
-When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreated` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event] will also be emitted.
+When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreatedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event] will also be emitted.
For this to work the target class _must_ have a no-arg constructor.
http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
index c169866..8b18b60 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
@@ -30,6 +30,20 @@ customer.setLastName(lastName);
repositoryService.persist(customer);
----
+It's worth being aware that the framework does _not_ eagerly persist the object.
+Rather, it queues up an internal command structure representing the object persistence request.
+This is then executed either at the end of the transaction, or if a xref:../ugfun/ugfun.adoc#_ugfun_crud_finding[query is run], or if the internal queue is manually flushed using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]'s `flush()` method.
+
+Alternatively, you can use:
+
+[source,java]
+----
+repositoryService.persistAndFlush(customer);
+----
+
+to eagerly perform the object insertion into the database.
+
+When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle events].
http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc
new file mode 100644
index 0000000..ee07bad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc
@@ -0,0 +1,25 @@
+[[_ugfun_crud_updating]]
+= Updating Objects
+: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/
+
+
+
+There is no specific API to update a domain entity.
+Rather, the ORM (DataNucleus) automatically keeps track of the state of each object and will update the corresponding database rows when the transaction completes.
+
+That said, it is possible to "flush" pending changes:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`] acts at the Apache Isis layer, and flushes any pending object persistence or object deletions
+
+* using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] it is possible to reach down to the underlying JDO API, and perform a flush of pending object updates also.
+
+
+When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle events].
+
+
+
+
+
+