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:12:59 UTC
[50/58] [abbrv] isis git commit: fixes FIXMEs in ugodn,
rearranging some content
fixes FIXMEs in ugodn, rearranging some content
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/cf86b157
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/cf86b157
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/cf86b157
Branch: refs/heads/wip
Commit: cf86b157d0e37ee669234da53f0f2354e8591a11
Parents: d9de887
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Apr 20 07:46:30 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/guides/dg/_dg_ide.adoc | 3 +-
.../asciidoc/guides/dg/_dg_ide_eclipse.adoc | 2 +-
.../_rgfis_spi_ContentNegotiationService.adoc | 2 +-
.../guides/ugodn/_ugodn_configuring.adoc | 3 +-
.../_ugodn_configuring_persistence-xml.adoc | 28 ++++++++++++-
.../guides/ugodn/_ugodn_hints-and-tips.adoc | 2 -
...ndling-mandatory-properties-in-subtypes.adoc | 44 --------------------
..._ugodn_hints-and-tips_mapping-to-a-view.adoc | 9 ----
.../guides/ugodn/_ugodn_jdo-mappings.adoc | 2 +
...ppings_mandatory-properties-in-subtypes.adoc | 44 ++++++++++++++++++++
.../_ugodn_jdo-mappings_mapping-to-a-view.adoc | 18 ++++++++
11 files changed, 97 insertions(+), 60 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
index db76f89..ca81d39 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
@@ -7,7 +7,8 @@
-The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
+The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do likewise as you develop your Apache Isis applications using an IDE.
+Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index a3f0dab..43ff34f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -90,7 +90,7 @@ When the enhancer runs, it will print out to the console:
image::{_imagesdir}eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
-
+[[__dg_ide_eclipse_workaround-for-path-limits]]
=== Workaround for path limits (the DN plugin to use the persistence.xml)
If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 0342d47..b4d62d7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -18,7 +18,7 @@ Instead you need to create some sort of stable facade over your domain entities,
+
If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips_mapping-to-a-view[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_jdo-mappings_mapping-to-a-view[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
+
If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
index 1734c98..5614dbe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
@@ -6,7 +6,8 @@
Apache Isis programmatically configures DataNucleus; any Apache Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
-DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit". n theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
+DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".
+In theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`. A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here]. The metadata in these XML can be used to override the annotations of annotated entities; see xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
index db4a42e..cbfbad4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
@@ -5,6 +5,32 @@
:_imagesdir: images/
-NOTE: FIXME
+DataNucleus will for itself also and read the `META-INF/persistence.xml`.
+In theory it can hold mappings and even connection strings.
+However, with Apache Isis we tend to use annotations instead and externalize connection strings. so its definition is extremely simply, specifying just the name of the "persistence unit".
+Here's the one provided by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+ <persistence-unit name="simple">
+ </persistence-unit>
+</persistence>
+----
+
+Normally all one needs to do is to change the `persistence-unit` name.
+
+[TIP]
+====
+If you use Eclipse IDE on Windows then xref:../dg/dg.adoc#__dg_ide_eclipse_workaround-for-path-limits[note the importance] of the `persistence.xml` file to make DataNucleus enhancer work correctly.
+====
+
+
+
+See link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistenceunit[DataNucleus' documentation] on `persistence.xml` to learn more.
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
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 1efd665..7f02c3b 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
@@ -23,8 +23,6 @@ See also hints-n-tips chapters in the:
include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-include::_ugodn_hints-and-tips_mapping-to-a-view.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]
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
deleted file mode 100644
index eff87e0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes]]
-= Handling Mandatory Properties in Subtypes
-: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/
-
-
-
-If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
-
-* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
-+
-whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
-
-* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
-+
-whereby there is a table for both superclass and subclass, in 1:1 correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
- @javax.jdo.annotations.Column(allowsNull="true")
- @Property(optionality=Optionality.MANDATORY)
- @lombok.Getter @lombok.Setter
- private LocalDate date;
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
deleted file mode 100644
index a50c2a0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugodn_hints-and-tips_mapping-to-a-view]]
-= Mapping to a View
-: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/
-
-
-NOTE: FIXME - as per Estatio's Invoice stuff
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
index 7a7de94..18a8b08 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
@@ -8,3 +8,5 @@
include::_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings_mapping-to-a-view.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
new file mode 100644
index 0000000..1720d5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
@@ -0,0 +1,44 @@
+[[_ugodn_jdo-mappings_mandatory-properties-in-subtypes]]
+= Mandatory Properties in Subtypes
+: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/
+
+
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby there is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+ @javax.jdo.annotations.Column(allowsNull="true")
+ @Property(optionality=Optionality.MANDATORY)
+ @lombok.Getter @lombok.Setter
+ private LocalDate date;
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
new file mode 100644
index 0000000..e9311f4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
@@ -0,0 +1,18 @@
+[[_ugodn_jdo-mappings_mapping-to-a-view]]
+= Mapping to a View
+: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/
+
+
+JDO/DataNucleus supports the ability to map the entity that is mapped to a view rather than a database table.
+Moreover, DataNucleus itself can create/maintain this view.
+
+One use case for this is to support use cases which act upon aggregate information.
+An link:https://github.com/estatio/estatio/blob/b77d0b03ec86463227ba90f8341299066ddba69f/estatioapp/module/lease/dom/src/main/java/org/estatio/dom/lease/invoicing/viewmodel/InvoiceSummaryForPropertyDueDateStatus.java#L57[example] is in the (non-ASF) http://github.com/estatio/estatio[Estatio] application, which uses a view to define an "invoice run": a representatoin of all pending invoices to be sent out for a particular shopping centre.
+(Note that example also shows the entity as being "non-durable", but if the view is read/write then -- I think -- that this isn't necessary required).
+
+
+For more on this topic, see the link:http://www.datanucleus.org/products/datanucleus/jdo/mapping.html#schema_rdbms_views[DataNucleus documentation].
+
+