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 2016/04/26 20:24:39 UTC
[4/6] isis git commit: ISIS-1392: minor edits to updated docs
ISIS-1392: minor edits to updated docs
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/78b70ade
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/78b70ade
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/78b70ade
Branch: refs/heads/master
Commit: 78b70ade82bf5e398783343a1a710e7dba6bb1cf
Parents: 219e63a
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Apr 26 19:01:04 2016 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Apr 26 19:01:04 2016 +0100
----------------------------------------------------------------------
.../guides/_rgsvc_api_RepositoryService.adoc | 152 +++++++++----------
1 file changed, 71 insertions(+), 81 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/78b70ade/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
index 9f33e5d..5aafe76 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_RepositoryService.adoc
@@ -25,12 +25,12 @@ The API of `RepositoryService` is:
[source,java]
----
public interface RepositoryService {
-
<T> T instantiate(final Class<T> ofType); // <1>
boolean isPersistent(Object domainObject); // <2>
void persist(Object domainObject); // <3>
void persistAndFlush(Object domainObject); // <4>
+
void remove(Object persistentDomainObject); // <5>
void removeAndFlush(Object persistentDomainObject); // <6>
@@ -44,7 +44,6 @@ public interface RepositoryService {
<T> T firstMatch(Query<T> query); // <12>
<T> T firstMatch(final Class<T> ofType, final Predicate<T> predicate); // <13>
-
}
----
<1> create a new non-persisted domain entity. This is identical to
@@ -52,9 +51,9 @@ xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`]'s `instantiate(...)`
``RepositoryService``'s API too because instantiating and persisting objects are often done together.
<2> test whether a particular domain object is persistent or not
<3> persist (ie save) an object to the persistent object store (or do nothing if it is already persistent).
-<4> persistAndFlush (ie save and flush) same as "persist()", but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the Persistence Mechanism - such as DataNucleus -).
+<4> (`1.13.0-SNAPSHOT`) persist (ie save) and flush; same as `persist()`, but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the DataNucleus persistence mechanism).
<5> remove (ie delete) an object from the persistent object store (or do nothing if it has already been deleted).
-<6> remove (ie delete and flush) same as "remove()", but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the Persistence Mechanism - such as DataNucleus -).
+<6> (`1.13.0-SNAPSHOT`) remove (delete) and flush; same as `remove()`, but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the DataNucleus persistence mechanism).
<7> return all persisted instances of specified type. Mostly for prototyping, though can be useful to obtain all instances of domain entities if the number is known to be small. The optional varargs parameters are for paging control; more on this below.
<8> all persistence instances matching the specified `Query`. Query itself is an Isis abstraction on top of JDO/DataNucleus' Query API. *This is the primary API used for querying*
<9> As the previous, but with client-side filtering using a `Predicate`. Only really intended for prototyping.
@@ -69,113 +68,104 @@ The `uniqueMatch(...)` methods are the recommended way of querying for (precisel
== Usage
-This section briefly discusses how application code can use these APIs.
+This section briefly discusses how application code can use (some of) these APIs.
-=== "persistAndFlush(..)", "removeAndFlush(...)"
-
-In some cases, such as when using Managed Properties and Collections for implementing 1-1, 1-n, or m-n relationships, the user needs to invoke "flush()" to send the changes to the persistence mechanism (such as JDO/DataNucleus).
-Then is when the persistence mechanism updates the managed properties and collections.
-
+=== Persist
[source,java]
----
-public abstract class Warehouse extends SalesVIPEntity<Marketplace> {
+Customer cust = repositoryService.instantiate(Customer.class);
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+repositoryService.persist(cust);
+----
- // {{ ExcludedProducts (Collection)
- @Persistent(mappedBy = "marketplace", dependentElement = "true")
- private SortedSet<MarketplaceExcludedProduct> excludedProducts = new TreeSet<MarketplaceExcludedProduct>();
+You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`. These are then executed either when the request completes (and the transaction commits), or if the queue is flushed. This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
- @MemberOrder(sequence = "1")
- public SortedSet<MarketplaceExcludedProduct> getExcludedProducts() {
- return this.excludedProducts;
- }
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
- public void setExcludedProducts(
- final SortedSet<MarketplaceExcludedProduct> excludedProducts) {
- this.excludedProducts = excludedProducts;
- }
- // }}
- // {{ addExcludedProduct (action)
+=== `persistAndFlush(...)`, `removeAndFlush(...)`
+
+In some cases, such as when using managed properties and collections for implementing 1-1, 1-n, or m-n relationships,
+the developer needs to invoke `flush()` to send the changes to the DataNucleus persistence mechanism. These
+managed properties and collections and then updated.
+
+The `persistAndFlush(...)` and `removeAndFlush(...)` methods (introduced in `1.13.0-SNAPSHOT`) save the developer from
+having to call the `flush(...)` method.
+
+For example, the following code requires a flush to occur, so uses these methods:
+
+[source,java]
+----
+public abstract class Warehouse extends SalesVIPEntity<Marketplace> {
+
+ @Persistent(mappedBy = "marketplace", dependentElement = "true")
+ @Getter @Setter // <1>
+ private SortedSet<MarketplaceExcludedProduct> excludedProducts =
+ new TreeSet<MarketplaceExcludedProduct>();
+
@Action(semantics = SemanticsOf.IDEMPOTENT)
- @MemberOrder(sequence = "1")
public MarketplaceExcludedProduct addExcludedProduct(final Product product) {
- MarketplaceExcludedProduct marketplaceExcludedProduct = this
- .findExcludedProduct(product);
- if (marketplaceExcludedProduct == null) {
- marketplaceExcludedProduct = this.factoryService
- .instantiate(MarketplaceExcludedProduct.class);
- }
-
- this.wrap(marketplaceExcludedProduct).setMarketplace(this);
- this.wrap(marketplaceExcludedProduct).setProduct(product);
+ MarketplaceExcludedProduct marketplaceExcludedProduct = this.findExcludedProduct(product);
+ if (marketplaceExcludedProduct == null) {
+ marketplaceExcludedProduct =
+ this.factoryService.instantiate(MarketplaceExcludedProduct.class);
+ }
- this.repositoryService.persistAndFlush(marketplaceExcludedProduct); // <— Needed for updating the managed properties and collections.
+ this.wrap(marketplaceExcludedProduct).setMarketplace(this);
+ this.wrap(marketplaceExcludedProduct).setProduct(product);
- return marketplaceExcludedProduct;
+ this.repositoryService.persistAndFlush(marketplaceExcludedProduct); // <2>
+ return marketplaceExcludedProduct;
}
- // }}
-
- // {{ deleteFromExcludedProducts (action)
@Action(semantics = SemanticsOf.IDEMPOTENT)
- @MemberOrder(sequence = "1")
public void deleteFromExcludedProducts(final Product product) {
- final MarketplaceExcludedProduct marketplaceExcludedProduct = this
- .findExcludedProduct(product);
- if (marketplaceExcludedProduct != null) {
- this.repositoryService.remove(marketplaceExcludedProduct);
- this.flushTransaction();
- }
+ final MarketplaceExcludedProduct marketplaceExcludedProduct = findExcludedProduct(product);
+ if (marketplaceExcludedProduct != null) {
+ this.repositoryService.removeAndFlush(marketplaceExcludedProduct);
+ }
}
-
- // }}
+ ... // <3>
+}
----
+<1> using lombok for brevity
+<2> Needed for updating the managed properties and collections.
+<3> injected services and other methods ommited
-On the “addExcludedProduct()” action, if the user don’t flush, this test would fail, as the managed collection would not containing the given product:
+On the “addExcludedProduct()” action, if the user didn’t flush, the following test would fail because the managed
+collection would not containing the given product:
[source,java]
----
- @Test
- public void addExcludedProduct() {
-
- // given
- final AmazonMarketplace amazonMarketplace = this.wrapSkipRules(
- this.marketplaceRepository).findOrCreateAmazonMarketplace(
- AmazonMarketplaceLocation.FRANCE);
-
- final Product product = this.wrap(this.productRepository)
- .createProduct(UUID.randomUUID().toString(),
- UUID.randomUUID().toString());
-
- // when
- this.wrap(amazonMarketplace).addExcludedProduct(product);
-
- // then
- Assertions.assertThat(this.wrapSkipRules(amazonMarketplace).findAllProductsExcluded()).contains(product); // <-- this would fail.
-
- }
-
-----
+@Test
+public void addExcludedProduct() {
-=== Query
+ // given
+ final AmazonMarketplace amazonMarketplace = this.wrapSkipRules(
+ this.marketplaceRepository).findOrCreateAmazonMarketplace(
+ AmazonMarketplaceLocation.FRANCE);
-[source,java]
-----
-Customer cust = repositoryService.instantiate(Customer.class);
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-repositoryService.persist(cust);
-----
+ final Product product = this.wrap(this.productRepository)
+ .createProduct(UUID.randomUUID().toString(), UUID.randomUUID().toString());
-You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`. These are then executed either when the request completes (and the transaction commits), or if the queue is flushed. This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
+ // when
+ this.wrap(amazonMarketplace).addExcludedProduct(product);
+
+ // then
+ Assertions.assertThat(
+ this.wrapSkipRules(amazonMarketplace).findAllProductsExcluded()
+ ).contains(product); // <1>
+}
+----
+<1> this would fail.
-By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
-=== Query
+=== Query and `xxxMatches(...)`
There are various implementations of the `Query` API, but these either duplicate functionality of the other overloads of `allMatches(...)` or they are not supported by the JDO/DataNucleus object store. The only significant implementation of `Query` to be aware of is `QueryDefault`, which identifies a named query and a set of parameter/argument tuples.