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/10/06 08:35:54 UTC
[isis] 13/13: ISIS-1742: updates docs,
removal of query APIs from DomainObjectContainer
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch dev/2.0.0/ISIS-1742-remove-deprecations
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 136a7127ac759638cdc96d9c74caa660f27d8428
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Oct 5 17:54:22 2017 +0300
ISIS-1742: updates docs, removal of query APIs from DomainObjectContainer
---
...gsvc_core-domain-api_DomainObjectContainer.adoc | 1 -
...mainObjectContainer_generic-repository-api.adoc | 84 ----------------------
...mainObjectContainer_object-persistence-api.adoc | 3 +-
...rgsvc_persistence-layer-api_IsisJdoSupport.adoc | 2 +-
...vc_persistence-layer-api_RepositoryService.adoc | 3 +-
5 files changed, 5 insertions(+), 88 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc
index e044413..8a56bb8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer.adoc
@@ -22,7 +22,6 @@ The sections below discuss the functions provided by the service, broken out int
include::_rgsvc_core-domain-api_DomainObjectContainer_object-creation-api.adoc[leveloffset=+2]
-include::_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc[leveloffset=+2]
include::_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc[leveloffset=+2]
include::_rgsvc_core-domain-api_DomainObjectContainer_messages-api.adoc[leveloffset=+2]
include::_rgsvc_core-domain-api_DomainObjectContainer_security-api.adoc[leveloffset=+2]
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc
deleted file mode 100644
index bb922ec..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-[[_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api]]
-= Generic Repository API
-: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 ag [...]
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-The repository API acts as an abstraction over the JDO/DataNucleus objectstore. You can use it during prototyping to write naive queries (find all rows, then filter using the Guava `Predicate` API, or you can use it to call JDO link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/query.html#named[named queries] using JDOQL.
-
-As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_IsisJdoSupport[`IsisJdoSupport`] service.
-
-
-[source,java]
-----
-public interface DomainObjectContainer {
- public <T> List<T> allInstances(Class<T> ofType, long... range); // <1>
- <T> List<T> allMatches(Query<T> query); // <2>
- <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long... range); // <3>
- <T> List<T> allMatches(Class<T> ofType, String title, long... range); // <4>
- <T> List<T> allMatches(Class<T> ofType, T pattern, long... range); // <5>
- ...
-}
-----
-<1> 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.
-<2> 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*
-<3> all persistenced instances of specified type matching `Predicate`. Only really intended for prototyping because in effect constitutes a client-side WHERE clause
-<4> all persisted instances with the specified string as their title. Only very occasionally used
-<5> all persisted instances matching object (query-by-example). Only very occasionally used
-
-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.
-
-For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] the `ToDoItem` is annotated:
-
-[source,java]
-----
-@javax.jdo.annotations.Queries( {
- @javax.jdo.annotations.Query(
- name = "findByAtPathAndComplete", language = "JDOQL", // <1>
- value = "SELECT "
- + "FROM todoapp.dom.module.todoitem.ToDoItem "
- + "WHERE atPath.indexOf(:atPath) == 0 " // <2>
- + " && complete == :complete"), // <3>
- ...
-})
-public class ToDoItem ... {
- ...
-}
-----
-<1> name of the query
-<2> defines the `atPath` parameter
-<3> defines the `complete` parameter
-
-This JDO query definitions are used in the `ToDoItemRepositoryImplUsingJdoql` service:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class ToDoItemRepositoryImplUsingJdoql implements ToDoItemRepositoryImpl {
- @Programmatic
- public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
- return container.allMatches(
- new QueryDefault<>(ToDoItem.class,
- "findByAtPathAndCategory", // <1>
- "atPath", atPath, // <2>
- "category", category)); // <3>
- }
- ...
- @javax.inject.Inject
- DomainObjectContainer container;
-}
-----
-<1> corresponds to the "findByAtPathAndCategory" JDO named query
-<2> provide argument for the `atPath` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
-<3> provide argument for the `category` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
-
-Other JDOQL named queries (not shown) follow the exact same pattern.
-
-With respect to the other query APIs, the varargs parameters are optional, but allow for (client-side and managed) paging. The first parameter is the `start` (0-based, the second is the `count`.
-
-[TIP]
-====
-It is also possible to query using DataNucleus' type-safe query API. For more details, see xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_IsisJdoSupport[`IsisJdoSupport`].
-====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc
index f3ed151..f75f782 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc
@@ -50,7 +50,8 @@ container.persistIfNotAlready(cust);
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()`.
-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/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+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/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[above].
+However, this behaviour can be disabled using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_IsisJdoSupport.adoc
index 6c46609..f9fb125 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_IsisJdoSupport.adoc
@@ -118,7 +118,7 @@ public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Categor
[NOTE]
====
-You can find the full example of the JDOQL equivalent in the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+You can find the full example of the JDOQL equivalent in the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService`]
====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_RepositoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_RepositoryService.adoc
index e51cc95..3bad5ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_RepositoryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api_RepositoryService.adoc
@@ -83,7 +83,8 @@ repositoryService.persist(cust);
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()`.
-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/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`.
+However, this behaviour can be disabled using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
--
To stop receiving notification emails like this one, please contact
"commits@isis.apache.org" <co...@isis.apache.org>.