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 <d...@haywood-associates.co.uk>
Authored: Thu Apr 20 07:46:30 2017 +0100
Committer: Dan Haywood <d...@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].
+
+

Reply via email to