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 <d...@haywood-associates.co.uk> Authored: Mon Apr 17 21:01:45 2017 +0200 Committer: Dan Haywood <d...@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]. + + + + + +
