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/09 11:36:37 UTC
[isis] branch master updated: ISIS-1465: updates docs,
hint-n-tip for DN 4.x and structure of simpleapp
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 4145f77 ISIS-1465: updates docs, hint-n-tip for DN 4.x and structure of simpleapp
4145f77 is described below
commit 4145f77ad94d5696ba9ba95033f27ddff52ba992
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Oct 9 11:20:15 2017 +0100
ISIS-1465: updates docs, hint-n-tip for DN 4.x and structure of simpleapp
---
..._ugfun_getting-started_simpleapp-archetype.adoc | 37 +++++--
.../using-simple-app/structure/structure.png | Bin 0 -> 65860 bytes
.../using-simple-app/structure/structure.pptx | Bin 0 -> 42183 bytes
.../guides/ugodn/_ugodn_hints-and-tips.adoc | 3 +
.../_ugodn_hints-and-tips_diagnosing-n-plus-1.adoc | 16 +++
...-and-tips_typesafe-queries-and-fetchgroups.adoc | 112 +++++++++++++++++++++
.../images/hints-n-tips/diagnosing-n-plus-1.png | Bin 0 -> 143232 bytes
7 files changed, 159 insertions(+), 9 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index b18ed1e..c6c922b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -8,26 +8,45 @@
The quickest way to get started building an application "for real" is to run the `simpleapp` archetype.
Like the xref:ugfun.adoc#_ugfun_getting-started_helloworld-archetype[helloworld archetype], this too will generate a very simple one-class domain model (an entity called `SimpleObject` with a couple of properties).
-However, the generated application also provides more structure to assist you as your application grows.
-For example:
+However, the generated application also provides more structure to assist you as your application grows:
-* the application is multi-module, separating out the business logic (`module-simple` Maven module) from the bootstrapping modules (`application` Maven module and the `webapp` module)
+image::{_imagesdir}getting-started/using-simple-app/structure/structure.png[width="800px",link="{_imagesdir}getting-started/using-simple-app/structure/structure.png"]
-* the `SimpleObjectRepository` service (to create/retrieve instances) is separate from the `SimpleObjectMenu` menu service (for the UI); the former is delegated to by the latter.
+where `xxx` is the name of the `artifactId` that you supply when you run the archetype.
-* a `HomePageViewModel` service acts as a home page for the app.
+Specifically:
-* there are example integration tests, BDD tests as well as unit tests
+* the application is multi-module, separating out the business logic (`xxx-module-simple` Maven module) from the bootstrapping modules (`xxx-application` Maven module and the `xxx-webapp` module)
-* there are example fixture scripts for use both when prototyping and used by the integration and BDD tests
+* in the `xxx-module-simple` module, the `SimpleObjectRepository` service (to create/retrieve instances) is separate from the `SimpleObjectMenu` menu service (for the UI); the former is delegated to by the latter.
-* the xref:../rgmvn.adoc#[Apache Isis Maven plugin] to xref:../rgmvn.adoc#_rgmvn_validate[validate] your domain model is pre-configured
+* in the `xxx-application` module, a `HomePageViewModel` service acts as a home page for the app.
-* Maven plugins to package your app as a Docker image is pre-configured
+* there are example integration tests and BDD tests as well as unit tests
+
++
+There are "cross-module" integration tests in the `xxx-application` module.
+These bootstrap the application as a single entity so that these tests can exercise functionality in any and all modules.
+The BDD tests are also defined here are also "cross-module".
++
+There are also "per-module" integration tests in the `xxx-module-simple` module.
+
+* there are example fixture scripts for use both when prototyping and used by the integration and BDD tests.
+These tend to be defined in each individual module, ie `xxx-module-simple`.
+
+* the xref:../rgmvn.adoc#[Apache Isis Maven plugin] is configured to xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate] your domain model in the `module-simple` module
+
+* the xref:../rgmvn.adoc#[Apache Isis Maven plugin] is also configured to generate a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger] spec file for the entire application, in the `xxx-application` module
+
+* Maven plugins to package your app as a Docker image is pre-configured, in the `xxx-webapp` module.
From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+[TIP]
+====
+The (non-ASF) Incode Platform's link:http://platform.incode.org/quickstart/quickstart.html[quickstart archetype] builds upon the simpleapp archetype, but adds in support for various Incode Platform modules such as security, auditing, commands and publishing.
+====
[[__ugfun_getting-started_simpleapp-archetype_generating-the-app]]
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png
new file mode 100644
index 0000000..909d09b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.png differ
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx
new file mode 100644
index 0000000..230963a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/getting-started/using-simple-app/structure/structure.pptx differ
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 7f02c3b..297f13b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -27,3 +27,6 @@ include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_diagnosing-n-plus-1.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_typesafe-queries-and-fetchgroups.adoc[leveloffset=+1]
+
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_diagnosing-n-plus-1.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_diagnosing-n-plus-1.adoc
new file mode 100644
index 0000000..165cc9b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_diagnosing-n-plus-1.adoc
@@ -0,0 +1,16 @@
+[[_ugodn_hints-and-tips_diagnosing-n-plus-1]]
+= Diagnosing n+1 Issues
+: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/
+
+
+(As of DN 4.1) set a break point in `FetchRequest#execute(...)`:
+
+image::{_imagesdir}hints-n-tips/diagnosing-n-plus-1.png[width="800px",link="{_imagesdir}hints-n-tips/diagnosing-n-plus-1.png"]
+
+The "Variables" pane will tell you which field(s) are being loaded, and the stack trace should help explain why the field is required.
+
+For example, it may be that an object is being loaded in a table and the initial query did not eagerly load that field.
+In such a case, consider using fetch groups in the initial repository query to bring the required data into memory with just one SQL call.
+See xref:ugodb.adoc#_ugodn_hints-and-tips_typesafe-queries-and-fetchgroups[this hint/tip] for further details.
\ No newline at end of file
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_typesafe-queries-and-fetchgroups.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_typesafe-queries-and-fetchgroups.adoc
new file mode 100644
index 0000000..e9bfa3b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_typesafe-queries-and-fetchgroups.adoc
@@ -0,0 +1,112 @@
+[[_ugodn_hints-and-tips_typesafe-queries-and-fetchgroups]]
+= Typesafe Queries and Fetch-groups
+: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/
+
+
+
+Fetch groups provide a means to hint to DataNucleus that it should perform a SQL join when querying.
+A common use case is to avoid the xref:ugodn.adoc#_ugodn_hints-and-tips_diagnosing-n-plus-1[n+1] issue.
+
+(So far as I could ascertain) it isn't possible to specify fetch group hints using JDOQL, but it is possible to specify them using the programmatic API or using typesafe queries.
+
+For example, here's a JDOQL query:
+
+[source,java]
+----
+@Query(
+ name = "findCompletedOrLaterWithItemsByReportedDate", language = "JDOQL",
+ value = "SELECT "
+ + "FROM org.estatio.capex.dom.invoice.IncomingInvoice "
+ + "WHERE items.contains(ii) "
+ + " && (ii.reportedDate == :reportedDate) "
+ + " && (approvalState != 'NEW' && approvalState != 'DISCARDED') "
+ + "VARIABLES org.estatio.capex.dom.invoice.IncomingInvoiceItem ii "
+),
+public class IncomingInvoice ... { ... }
+----
+
+which normally would be used from a repository:
+
+
+[source,java]
+----
+public List<IncomingInvoice> findCompletedOrLaterWithItemsByReportedDate(
+ final LocalDate reportedDate) {
+ return repositoryService.allMatches(
+ new QueryDefault<>(
+ IncomingInvoice.class,
+ "findCompletedOrLaterWithItemsByReportedDate",
+ "reportedDate", reportedDate));
+}
+----
+
+
+This can be re-written as a type-safe query as follows:
+
+[source,java]
+----
+public List<IncomingInvoice> findCompletedOrLaterWithItemsByReportedDate(final LocalDate reportedDate) {
+
+ final QIncomingInvoice ii = QIncomingInvoice.candidate();
+ final QIncomingInvoiceItem iii = QIncomingInvoiceItem.variable("iii");
+
+ final TypesafeQuery<IncomingInvoice> q =
+ isisJdoSupport.newTypesafeQuery(IncomingInvoice.class);
+
+ q.filter(
+ ii.items.contains(iii)
+ .and(iii.reportedDate.eq(reportedDate))
+ .and(ii.approvalState.ne(IncomingInvoiceApprovalState.NEW))
+ .and(ii.approvalState.ne(IncomingInvoiceApprovalState.DISCARDED)));
+ final List<IncomingInvoice> incomingInvoices = Lists.newArrayList(q.executeList());
+ q.closeAll();
+ return incomingInvoices;
+}
+----
+
+Now the `IncomingInvoice` has four fields that require eager loading.
+This can be specified by defining a named fetch group:
+
+[source,java]
+----
+@FetchGroup(
+ name="seller_buyer_property_bankAccount",
+ members={
+ @Persistent(name="seller"),
+ @Persistent(name="buyer"),
+ @Persistent(name="property"),
+ @Persistent(name="bankAccount")
+ })
+public class IncomingInvoice ... { ... }
+----
+
+
+This fetch group can then be used in the query using `q.getFetchPlan().addGroup(...)`.
+Putting this all together, we get:
+
+[source,java]
+----
+public List<IncomingInvoice> findCompletedOrLaterWithItemsByReportedDate(final LocalDate reportedDate) {
+
+ final QIncomingInvoice ii = QIncomingInvoice.candidate();
+ final QIncomingInvoiceItem iii = QIncomingInvoiceItem.variable("iii");
+
+ final TypesafeQuery<IncomingInvoice> q =
+ isisJdoSupport.newTypesafeQuery(IncomingInvoice.class);
+
+ q.getFetchPlan().addGroup("seller_buyer_property_bankAccount"); // <1>
+
+ q.filter(
+ ii.items.contains(iii)
+ .and(iii.reportedDate.eq(reportedDate))
+ .and(ii.approvalState.ne(IncomingInvoiceApprovalState.NEW))
+ .and(ii.approvalState.ne(IncomingInvoiceApprovalState.DISCARDED)));
+ final List<IncomingInvoice> incomingInvoices = Lists.newArrayList(q.executeList());
+ q.closeAll();
+ return incomingInvoices;
+}
+----
+<1> specify the fetch group to use.
+
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/images/hints-n-tips/diagnosing-n-plus-1.png b/adocs/documentation/src/main/asciidoc/guides/ugodn/images/hints-n-tips/diagnosing-n-plus-1.png
new file mode 100644
index 0000000..b30741f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugodn/images/hints-n-tips/diagnosing-n-plus-1.png differ
--
To stop receiving notification emails like this one, please contact
['"commits@isis.apache.org" <co...@isis.apache.org>'].