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/03/31 07:10:55 UTC
[19/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc
deleted file mode 100644
index e8cf1a3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_application-menu.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-[[_ugfun_object-layout_application-menu]]
-= Application Menu Layout
-: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/
-
-
-
-The actions of domain services are made available as an application menu bar. By default each domain service
-corresponds to a single menu on this menu bar, with its actions as the drop-down menu items. This is rarely exactly
-what is required, however. The `@MemberOrder` and `@DomainServiceLayout` annotations can be used to rearrange the
-placement of menu items.
-
-The screenshots below are taken from http://github.com/estatio/estatio[Estatio], an open source estate management
-application built using Apache Isis.
-
-== @DomainServiceLayout
-
-Menus for domain services can be placed either on a primary, secondary or tertiary menu bar.
-
-image::{_imagesdir}wicket-viewer/application-menu/layout-menus.png[width="800px",link="{_imagesdir}wicket-viewer/application-menu/layout-menus.png"]
-
-Within a single top-level menu (eg "Fixed Assets") there can be actions from multiple services. The Wicket viewer
-automatically adds a divider between each:
-
-image::{_imagesdir}wicket-viewer/application-menu/dividers.png[width="400px",link="{_imagesdir}wicket-viewer/application-menu/dividers.png"]
-
-In the example above the top-level menu combines the actions from the `Properties`, `Units` and `FixedAssetRegistrations`
-services. The `Properties` service is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Fixed Assets",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10.1"
-)
-public class Properties ... { ... }
-----
-
-while the `Units` service is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Fixed Assets",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10.2"
-)
-public class Units ... { ... }
-----
-
-and similarly `FixedAssetRegistrations` is annotated:
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Fixed Assets",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10.3"
-)
-public class FixedAssetRegistrations ... { ... }
-----
-
-Note that in all three cases the value of the `named` attribute and the `menuBar` attribute is the same: "Fixed Assets"
-and PRIMARY. This means that all will appear on a "Fixed Assets" menu in the primary menu bar.
-
-Meanwhile the value of `menuOrder` attribute is significant for two reasons:
-
-* for these three services on the same ("Fixed Assets") top-level menu, it determines the relative order of their sections (`Properties` first, then `Units`, then `FixedAssetRegistrations`)
-* it determines the placement of the top-level menu itself ("Fixed Assets") with respect to other top-level menus on the menu bar.
-
-To illustrate this latter point, the next top-level menu on the menu bar, "Parties", is placed after "Fixed Assets"
- because the `menuOrder` of the first of its domain services, namely the `Parties` service, is higher than that for
- "Fixed Assets":
-
-[source,java]
-----
-@DomainServiceLayout(
- named="Parties",
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "20.1"
-)
-public class Parties ... { ... }
-----
-
-Note that only the `menuOrder` of the _first_ domain service is significant in placing the menus along the menu bar;
-thereafter the purpose of the `menuOrder` is to order the menu services sections on the menu itself.
-
-== Ordering menu actions
-
-For a given service, the actions within a section on a menu is determined by the `@MemberOrder` annotation. Thus, for
-the `Units` domain service, its actions are annotated:
-
-[source,java]
-----
-public class Units extends EstatioDomainService<Unit> {
-
- @MemberOrder(sequence = "1")
- public Unit newUnit( ... ) { ... }
-
- @MemberOrder(sequence = "2")
- public List<Unit> findUnits( ... ) { ... }
-
- @ActionLayout( prototype = true )
- @MemberOrder(sequence = "99")
- public List<Unit> allUnits() { ... }
- ...
-}
-----
-
-Note that the last is also a prototype action (meaning it is only displayed in SERVER_PROTOTYPE (=Wicket Development) mode).
-In the UI it is rendered in italics.
-
-(It is possible to override this place of a given action by specifying `@MemberOrder(name="...")` where the name is
-that of a top-level menu. Prior to 1.8.0 this was the only way of doing things, as of 1.8.0 its use
-is not recommended).
-
-== Tertiary menubar
-
-The tertiary menu bar consists of a single unnamed menu, rendered underneath the user's login, top right. This is
-intended primarily for actions pertaining to the user themselves, eg their account, profile or settings:
-
-image::{_imagesdir}wicket-viewer/application-menu/tertiary.png[width="300px",link="{_imagesdir}wicket-viewer/application-menu/tertiary.png"]
-
-Domain services' actions can be associated with the tertiary menu using the same `@DomainServiceLayout` annotation. For
-example, the `updateEpochDate(...)` and `listAllSettings(...)` actions come from the following service:
-
-[source,java]
-----
-@DomainServiceLayout(
- menuBar = DomainServiceLayout.MenuBar.TERTIARY,
- menuOrder = "10.1"
-)
-public class EstatioAdministrationService ... {
-
- @MemberOrder(sequence = "1")
- public void updateEpochDate( ... ) { ... }
-
- @MemberOrder(sequence = "2")
- public List<ApplicationSetting> listAllSettings() { ... }
- ...
-}
-----
-
-Because the number of items on the tertiary menu is expected to be small and most will pertain to the current user, the
-viewer does _not_ place dividers between actions from different services on the tertiary menu.
-
-
-== Isis Add-on modules
-
-Some of the (non-ASF) link:http://isisaddons.org[Isis Addons] modules also provide services whose actions appear in top-level menus.
-
-The http://github.com/isisaddons/isis-module-security[security]'s module places its domain service menus in three
-top-level menus:
-
-* its `ApplicationUsers`, `ApplicationRoles`, `ApplicationPermission`, `ApplicationFeatureViewModels` and
- `ApplicationTenancies` domain services are all grouped together in a single "Security" top-level menu, on the
- SECONDARY menu bar
-
-* its `SecurityModuleAppFixturesService` domain service, which allows the security modules' fixture scripts to be run,
- is placed on a "Prototyping" top-level menu, also on the SECONDARY menu bar
-
-* its `MeService` domain service, which provides the `me()` action, is placed on the TERTIARY menu bar.
-
-Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module places its actions - to download layouts and
-so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
-
-Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
-using security or using a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
deleted file mode 100644
index 5596ed4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic.adoc
+++ /dev/null
@@ -1,151 +0,0 @@
-[[_ugfun_object-layout_dynamic]]
-= Dynamic (JSON) Layout
-: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/
-
-
-
-Metadata providing UI hints can be specified either xref:ugfun.adoc#_ugfun_object-layout_static[statically], using annotations, or dynamically, using either a xref:ugfun.adoc#_ugfun_object-layout_dynamic_xml[``layout.xml``] file or (as described here) a `.layout.json` file.
-
-
-[IMPORTANT]
-====
-The use of dynamic layouts through the `.layout.json` is DEPRECATED. Instead, use the
-``.layout.xml`` file, which enables much more sophisticated custom layouts than those provided by ``.layout.json``.
-
-It is possible to download initial `.layout.xml` files - which will capture all the metadata originally in the `.layout.json` file - using the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed as an action on the prototyping menu).
-The `.layout.json` file will be ignored once a `.layout.xml` file is present.
-====
-
-== JSON layout file
-
-The JSON layout file for class `Xxx` takes the name `Xxx.layout.json`, and resides in the same package as the class.
-
-
-The format of the file is:
-
-[source,javascript]
-----
-{
- "columns": [ // list of columns
- {
- "span": 6, // span of the left-hand property column
- "memberGroups": { // ordered map of member (property) groups
- "General": { // member group name
- "members": {
- "description": { // property, no associated actions, but with UI hint
- "propertyLayout": {
- "typicalLength": 50 // UI hint for size of field (no longer used in ISIS 1.8.0)
- }
- },
- "category": {},
- "complete": { // property, with associated actions
- "propertyLayout": {
- "describedAs": "Whether this todo item has been completed"
- },
- "actions": {
- "completed": {
- "actionLayout": {
- "named": "Done", // naming UI hint
- "cssClass": "x-highlight" // CSS UI hint
- }
- },
- "notYetCompleted": {
- "actionLayout": {
- "named": "Not done"
- }
- }
- }
- }
- },
- "Misc": {
- "members": {
- "notes": {
- "propertyLayout": {
- "multiLine": 5 // UI hint for text area
- }
- },
- "versionSequence": {}
- }
- }
- }
- }
- },
- {
- "span": 6, // span of the middle property column
- "memberGroups": { ... }
- },
- {
- "span": 0 // span of the right property column (if any)
- },
- {
- "span": 6,
- "collections": { // ordered map of collections
- "dependencies": { // collection, with associated actions
- "collectionLayout": {
- "paged": 10, // pagination UI hint
- "render": "EAGERLY" // lazy-loading UI hint
- },
- "actions": {
- "add":{},
- "delete": {}
- },
- },
- "similarItems": {} // collection, no associated actions
- }
- }
- ],
- "actions": { // actions not associated with any member
- "delete": {},
- "duplicate": {
- "actionLayout": {
- "named": {
- "value": "Clone"
- }
- }
- }
- }
-}
-----
-
-Although advisable, it is not necessary to list all class members in this file. Any members not listed with be
-ordered according either to annotations (if present) or fallback/default values.
-
-Note also that the layout file may contain entries for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions]; this allows each contributee classes to define their own layout for their contributions, possibly overriding any static metadata on the original domain service contributor.
-
-
-
-== Downloading an initial layout
-
-The fastest way to get started is to use the (non-ASF) link:http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module to download the layout file (derived from any existing static metadata defined by annotations).
-
-
-
-== Required updates to the dom project's pom.xml
-
-Any `.layout.json` files must be compiled and available in the classpath. Ensure the following is defined in the dom project's `pom.xml`:
-
-[source.xml]
-----
-<resources>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/resources</directory>
- </resource>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/java</directory>
- <includes>
- <include>**</include>
- </includes>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
- </resource>
-</resources>
-----
-
-If using an Apache Isis xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
deleted file mode 100644
index 7eb007d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
+++ /dev/null
@@ -1,400 +0,0 @@
-[[_ugfun_object-layout_dynamic_xml]]
-= Dynamic (XML) Layout
-: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/
-
-
-
-Metadata providing UI hints can be specified either xref:ugfun.adoc#_ugfun_object-layout_static[statically], using annotations, or dynamically using an `Xxx.layout.xml` file (where `Xxx` is the entity or view model object to be rendered).
-
-The `Xxx.layout.xml` file is just the serialized form of a xref:rgcms.adoc#_rgcms_classes_layout[`Grid`] layout class defined within Apache Isis' applib. These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that
-is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making iteasy to author such layout files.
-
-It is also possible to download an initial `.layout.xml` - capturing any existing layout metadata - using the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed on the prototyping menu) or using a xref:rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] contributed to every domain object.
-
-[NOTE]
-====
-It is also possible to describe dynamic layouts using a `.layout.json` file, as discussed xref:ugfun.adoc#_ugfun_object-layout_dynamic[here]. The `.layout.json` file should be considered as deprecated: the ``.layout.xml`` file also enables much more sophisticated layouts than those afforded by ``.layout.json``.
-====
-
-== Grids vs Components
-
-The XML file distinguishes between two types of element:
-
-* those that define a grid structure, of: rows, columns, tab groups and tabs. +
-+
-The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:ugvw.adoc[Wicket viewer]).
-
-* those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
-
-More information about these classes can be found in xref:rgcms.adoc#_rgcms_classes_layout[the reference guide]. More information on Bootstrap 3's grid system can be found link:http://getbootstrap.com/css/#grid[here].
-
-
-== Screencast
-
-This link:https://www.youtube.com/watch?v=MxewC5Pve5k[screencast] describes the feature.
-
-
-
-
-== Examples
-
-Probably the easiest way to understand dynamic XML layouts is by example. For this we'll use the `ToDoItem` from the
-(non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
-
-image::{_imagesdir}ugfun/_ugfun_object-layout_dynamic_xml/ToDoItem.png[width="940px",link="{_imagesdir}ugfun/_ugfun_object-layout_dynamic_xml/ToDoItem.png"]
-
-
-=== Namespaces
-
-First things first; every `.layout.xml` file must properly declare the XSD namespaces and schemas. There are two: one for the grid classes, and one for the common component classes:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<bs3:grid
- xsi:schemaLocation="http://isis.apache.org/applib/layout/component
- http://isis.apache.org/applib/layout/component/component.xsd
- http://isis.apache.org/applib/layout/grid/bootstrap3
- http://isis.apache.org/applib/layout/grid/bootstrap3/bootstrap3.xsd"
- xmlns:bs3="http://isis.apache.org/applib/layout/grid/bootstrap3"
- xmlns:c="http://isis.apache.org/applib/layout/component"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- ...
-</bs3:grid>
-----
-
-Most IDEs will automatically download the XSD schemas from the specified schema locations, thereby providing
-"intellisense" help as you edit the file.
-
-
-=== Rows, full-width cols, and tabs
-
-The example layout consists of three rows: a row for the object/icon, a row containing a properties, and a row containing collections. In all three cases the row contains a single column spanning the full width of the page. For the property and collection rows, the column contains a tab group.
-
-This corresponds to the following XML:
-
-[source,xml]
-----
- <bs3:row>
- <bs3:col span="12" unreferencedActions="true">
- <c:domainObject bookmarking="AS_ROOT"/>
- </bs3:col>
- </bs3:row>
- <bs3:row>
- <bs3:col span="12">
- <bs3:tabGroup>
- <bs3:tab name="Properties">...</bs3:tab>
- <bs3:tab name="Other">...</bs3:tab>
- <bs3:tab name="Metadata">...</bs3:tab>
- </bs3:tabGroup>
- </bs3:col>
- </bs3:row>
- <bs3:row>
- <bs3:col span="12">
- <bs3:tabGroup unreferencedCollections="true">
- <bs3:tab name="Similar to">...</bs3:tab>
- <bs3:tab name="Dependencies">...</bs3:tab>
- </bs3:tabGroup>
- </bs3:col>
- </bs3:row>
-----
-
-
-You will notice that one of the ``col``umns has an ``unreferencedActions`` attribute, while one of the ``tabGroup``s has a similar ``unreferencedCollections`` attribute. This topic is discussed in more detail xref:ugfun.adoc#__ugfun_object-layout_dynamic_xml-unreferenced[below].
-
-
-
-=== Fieldsets
-
-The first tab containing properties is divided into two columns, each of which holds a single fieldset of multiple properties. Those properties in turn can have associated actions.
-
-This corresponds to the following XML:
-
-[source,xml]
-----
- <bs3:tab name="Properties">
- <bs3:row>
- <bs3:col span="6">
- <c:fieldSet name="General" id="general" unreferencedProperties="true">
- <c:action id="duplicate" position="PANEL_DROPDOWN"/>
- <c:action id="delete"/>
- <c:property id="description"/>
- <c:property id="category"/>
- <c:property id="subcategory">
- <c:action id="updateCategory"/>
- <c:action id="analyseCategory" position="RIGHT"/>
- </c:property>
- <c:property id="complete">
- <c:action id="completed" cssClassFa="fa-thumbs-up"/>
- <c:action id="notYetCompleted" cssClassFa="fa-thumbs-down"/>
- </c:property>
- </c:fieldSet>
- </bs3:col>
- <bs3:col span="6">
- ...
- </bs3:col>
- </bs3:row>
- </bs3:tab>
-----
-
-The tab defines two columns, each span of 6 (meaning half the width of the page).
-
-In the first column there is a single fieldset. Notice how actions - such as `duplicate` and `delete` - can be associated with this fieldset directly, meaning that they should be rendered on the fieldset's top panel.
-
-Thereafter the fieldset lists the properties in order. Actions can be associated with properties too; here they are rendered underneath or to the right of the field.
-
-Note also the `unreferencedProperties` attribute for the fieldset; this topic is discussed in more detail xref:ugfun.adoc#__ugfun_object-layout_dynamic_xml-unreferenced[below].
-
-
-=== Collections
-
-In the final row the collections are placed in tabs, simply one collection per tab. This corresponds to the following XML:
-
-[source,xml]
-----
- <bs3:tab name="Similar to">
- <bs3:row>
- <bs3:col span="12">
- <c:collection defaultView="table" id="similarTo"/>
- </bs3:col>
- </bs3:row>
- </bs3:tab>
- <bs3:tab name="Dependencies">
- <bs3:row>
- <bs3:col span="12">
- <c:collection defaultView="table" id="dependencies">
- <c:action id="add"/>
- <c:action id="remove"/>
- </c:collection>
- </bs3:col>
- </bs3:row>
- </bs3:tab>
-----
-
-As with properties, actions can be associated with collections; this indicates that they should be rendered in the collection's header.
-
-
-
-[[__ugfun_object-layout_dynamic_xml-unreferenced]]
-== Unreferenced Members
-
-As noted in the preceding discussion, several of the grid's regions have either an ``unreferencedActions``, ``unreferencedCollections`` or ``unreferencedProperties`` attribute.
-
-The rules are:
-
-* `unreferencedActions` attribute can be specified either on a column or on a fieldset. +
-+
-It would normally be typical to use the column holding the `<domainObject/>` icon/title, that is as shown in the example. The unreferenced actions then appear as top-level actions for the domain object.
-
-* `unreferencedCollections` attribute can be specified either on a column or on a tabgroup. +
-+
-If specified on a column, then that column will contain each of the unreferenced collections, stacked one on top of the other. If specified on a tab group, then a separate tab will be created for each collection, with that tab containing only that single collection.
-
-* `unreferencedProperties` attribute can be specified only on a fieldset.
-
-The purpose of these attributes is to indicate where in the layout any unreferenced members should be rendered. Every grid _must_ nominate one region for each of these three member types, the reason being that to ensure that the layout can be used even if it is incomplete with respect to the object members inferred from the Java source code. This might be because the developer forgot to update the layout, or it might be because of a new mixin (property, collection or action) contributed to many objects.
-
-
-The framework ensures that in any given grid exactly one region is specified for each of the three `unreferenced...` attributes. If the grid fails this validation, then a warning message will be displayed, and the invalid XML logged. The layout XML will then be ignored.
-
-
-
-== More advanced features
-
-This section decribes a number of more features useful in more complex layouts.
-
-
-=== Multiple references to a feature
-
-One feature worth being aware of is that it is possible to render a single feature more than once.
-
-For example, the dashboard home page for the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] shows
-the "not yet complete" collection of todo items twice, once as a table and also as a calendar:
-
-image::{_imagesdir}ugfun/_ugfun_object-layout_dynamic_xml/ToDoAppDashboard.png[width="940px",link="{_imagesdir}ugfun/_ugfun_object-layout_dynamic_xml/ToDoAppDashboard.png"]
-
-
-This is accomplished using the following (slightly abbreviated) layout:
-
-[source,xml]
-----
-<grid ...>
- <row>
- <col span="2" unreferencedActions="true">
- ...
- </col>
- <col span="5" unreferencedCollections="true" cssClass="custom-padding-top-20">
- <ns2:collection id="notYetComplete" defaultView="calendar"/> <!--1-->
- </col>
- <col span="5" cssClass="custom-padding-top-20">
- <ns2:collection id="notYetComplete" defaultView="table" paged="5"/> <!--2-->
- <ns2:collection id="complete" defaultView="table"/>
- </col>
- <col span="0">
- <ns2:fieldSet name="General" id="general" unreferencedProperties="true"/>
- </col>
- </row>
-</grid>
-----
-<1> render the collection in "calendar" view
-<2> also render the collection in "table" view
-
-In the middle column the `notYetComplete` collection is rendered in "calendar" view, while in the right-most column
-it is rendered in "table" view.
-
-
-It is also possible to reference object properties and actions more than once. This might be useful for a complex
-domain object with multiple tabs; certain properties or actions might appear on a summary tab (that shows the
-most commonly used info), but also on detail tabs.
-
-=== Custom CSS
-
-The ToDoApp's dashboard (above) also shows how custom CSS styles can be associated with specific regions of the layout:
-
-[source,xml]
-----
-<grid ...>
- <row>
- <col span="2" unreferencedActions="true">
- <ns2:domainObject/>
- <row>
- <col span="12" cssClass="custom-width-100"> <!--1-->
- <ns2:action id="exportToWordDoc"/>
- </col>
- </row>
- ...
- </col>
- <col span="5" unreferencedCollections="true" cssClass="custom-padding-top-20"> <!--2-->
- ...
- </col>
- <col span="5" cssClass="custom-padding-top-20"> <!--3-->
- ...
- </col>
- </row>
-</grid>
-----
-<1> Render the column with the `custom-width-100` CSS class.
-<2> Render the column with the `custom-padding-top-20` CSS class.
-<3> Ditto
-
-For example the `custom-width-100` style is used to "stretch" the button for the `exportToWordDoc` action in the
-left-most column. This is accomplished with the following CSS in `application.css`:
-
-[source,css]
-----
-.custom-width-100 ul,
-.custom-width-100 ul li,
-.custom-width-100 ul li a.btn {
- width: 100%;
-}
-----
-
-Similarly, the middle and right columns are rendered using the `custom-padding-top-20` CSS class. This shifts them down
-from the top of the page slightly, using the following CSS:
-
-[source,css]
-----
-.custom-padding-top-20 {
- padding-top: 20px;
-}
-----
-
-
-
-
-== Migrating from earlier versions
-
-As noted earlier on, it is possible to download layout XML files using the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models. Alternatively the layout XML for a single domain object can be downloaded using the xref:rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] (contributed to every domain object).
-
-There are four "styles":
-
-* current
-* complete
-* normalized
-* minimal
-
-
-Ignorig the "current" style (which merely downloads the currently cached layout), the other three styles allow the
-developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained
-elsewhere, either from annotations in the metamodel or from an earlier `.layout.json` file if present. The table
-below summarises the choices:
-
-.Table caption
-[cols="<.>,^.>,^.>,^.>", options="header"]
-|===
-
-| Style
-|xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
-| xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
-| xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
-
-
-|`COMPLETE`
-|serialized as XML
-|serialized as XML
-|serialized as XML
-
-
-|`NORMALIZED`
-|serialized as XML
-|serialized as XML
-|not in the XML
-
-
-|`MINIMAL`
-|serialized as XML
-|not in the XML
-|not in the XML
-
-|===
-
-As a developer, you therefore have a choice as to how you provide the metadata required for customised layouts:
-
-* if you want all layout metadata to be read from the `.layout.xml` file, then download the "complete" version, and copy the file alongside the domain class. You can then remove all `@MemberGroupLayout`, `@MemberOrder`, `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations from the source code of the domain class.
-
-* if you want to use layout XML file to describe the grid (columns, tabs etc) and specify which object members are associated with those regions of the grid, then download the "normalized" version. You can then remove the `@MemberGroupLayout` and `@MemberOrder` annotations from the source code of the domain class, but retain the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations.
-
-* if you want to use layout XML file ONLY to describe the grid, then download the "minimal" version. The grid regions will be empty in this version, and the framework will use the `@MemberOrder` annotation to bind object members to those regions. The only annotation that can be safely removed from the source code with this style is the `@MemberGroupLayout` annotation.
-
-
-Download either for a single domain object, or download all domain objects (entities and view models).
-
-
-== Domain Services
-
-For more information about layouts, see:
-
-* xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (whose functionality is exposed on the prototyping menu as an action) and lso the a xref:rgcms .adoc#_rgcms_classes_mixins_Object[mixin action]
-
-* xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] and its supporting services, xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]
-
-* xref:rgcms.adoc#_rgcms_classes_layout[grid layout classes], defined in the Apache Isis applib
-
-
-== Required updates to the dom project's pom.xml
-
-Any `.layout.xml` files must be compiled and available in the classpath. Ensure the following is defined in the dom project's `pom.xml`:
-
-[source.xml]
-----
-<resources>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/resources</directory>
- </resource>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/java</directory>
- <includes>
- <include>**</include>
- </includes>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
- </resource>
-</resources>
-----
-
-If using an Apache Isis xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
deleted file mode 100644
index 980545c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static-vs-dynamic.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ugfun_object-layout_static-vs-dynamic]]
-= Static vs Dynamic Layouts
-: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/
-
-
-
-
-Using xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic object layout]s using JSON has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app. Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
-
-Another benefit of dynamic layout is that UI hints can be provided for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
-
-The main downsides of using dynamic layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid JSON document will result in no metadata for the entire class).
-
-Also, dynamic layouts have no notion of inheritance, whereas the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
-
-
-
-== Best of both worlds?
-
-Using the (non-ASF) link:http://github.com/isisaddons/isis-jrebel-plugin[Isis addons' jrebel] plugin comes close to getting the best of both words: metadata is specified in a type-safe way using annotations, but can be reloaded automatically.
-
-The downsides are licensing cost, and also the fact that metadata for contributed actions in the contributee class cannot be specified.
-
-Another open source alternative that you might also like to explore is DCEVM; there's a good write-up on the link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
deleted file mode 100644
index 6bd895d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
+++ /dev/null
@@ -1,178 +0,0 @@
-[[_ugfun_object-layout_static]]
-= Static Object Layout
-: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/
-
-
-Metadata providing UI hints can be specified either statically, using annotations, or dynamically, using either a xref:ugfun.adoc#_ugfun_object-layout_dynamic_xml[`layout.xml`] file or a xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file.
-
-This section describes the static approach, using annotations.
-
-[NOTE]
-====
-Tabs and tabgroups are only supported using xref:ugfun.adoc#_ugfun_object-layout_dynamic_xml[`layout.xml`] files; they are not supported by annotations.
-====
-
-
-
-== `@MemberOrder`
-
-The xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is used to specify the relative order of domain class properties, collections and actions.
-
-The annotation defines two attributes, xref:rgant.adoc#_rgant-MemberOrder_name[`name()`] and xref:rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`]. Their usage depends on the member type:
-
-* for properties, the `name()` is used to group properties together into a member group (also called a property group
-or a fieldset. The `sequence()` then orders properties within these groups. If no `name()` is specified then the
-property is placed in a fallback "General" group, called "General". +
-+
-The name of these member groups/fieldsets are then referenced by xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`].
-
-* for collections, the `name()` attribute is (currently) unused. The `sequence()` orders collections relative to one another
-
-* for actions, the `name()` attribute associates an action with either a property or with a collection. +
-
-** If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. +
-
-** On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header.
-
-** If there is no `name()` value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the object's icon and title.
-
-Within any of these, the `sequence()` then determines the relative ordering of the action with respect to other actions that have been similarly associated with properties/collections or left as "free-standing".
-
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @MemberOrder(sequence="1")
- public String getDescription() { ... }
- @MemberOrder(sequence="2")
- public String getCategory() { ... }
- @MemberOrder(sequence="3")
- public boolean isComplete() { ... }
- @MemberOrder(name="Detail", sequence="1")
- public LocalDate getDueBy() { ... }
- @MemberOrder(name="Detail", sequence="2")
- public BigDecimal getCost() { ... }
- @MemberOrder(name="Detail", sequence="4")
- public String getNotes() { ... }
- @MemberOrder(name="Misc", sequence="99")
- public Long getVersionSequence() { ... }
- ...
-}
-----
-
-This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
-
-In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the ``@MemberOrder``'s xref:rgant.adoc#_rgant-MemberOrder_name[`name()`] attribute, holding the value of the property or collection.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @MemberOrder(sequence="3")
- public boolean isComplete() { ... }
- @MemberOrder(name="complete", sequence="1")
- public ToDoItem completed() { ...}
- @MemberOrder(name="complete", sequence="2")
- public ToDoItem notYetCompleted() { ...}
-
- @MemberOrder(sequence="1")
- public SortedSet<ToDoItem> getDependencies() { ... }
- @MemberOrder(name="dependencies", sequence="1")
- public ToDoItem add(ToDoItem t) { ...}
- @MemberOrder(name="dependencies", sequence="2")
- public ToDoItem remove(ToDoItem t) { ...}
- ...
-}
-----
-
-will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
-
-
-The value of xref:rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`] is a string. The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.
-
-Even better is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion. It also allows subclasses to insert their class members as required.
-
-
-
-
-== `@MemberGroupLayout`
-
-The xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column. The annotation also specifies the relative width of the columns.
-
-The property groups/fieldsets in this case are those that are inferred from the `@MemberOrder#name()` attribute.
-
-[TIP]
-====
-It is also possible to combine `@MemberOrder` with dynamic layouts, either using xref:ugfun.adoc#_ugfun_object-layout_xml[XML] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[JSON]. The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does __not__ specify the properties/collections/actions within those grid regions. The `@MemberOrder` annotation in effect "binds" the properties or collections to those regions of the grid.
-
-When dynamic layouts are used this way, the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation is essentially ignored, but the metadata from the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation (and the other layout annotations, xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) are all still honoured.
-====
-
-For example:
-
-[source,java]
-----
-@MemberGroupLayout(
- columnSpans={3,3,0,6},
- left={"General", "Misc"},
- middle="Detail"
- )
-public class ToDoItem {
- ...
-}
-----
-
-Four values are given in the `columnSpans` attribute. The first three are the relative widths of the three columns of property groups. The fourth, meanwhile, indicates the width of a final column that holds all the collections of the object.
-
-The values of these spans are taken as proportions of 12 virtual columns across the page (this taken from the link:http://getbootstrap.com/2.3.2/[Bootstrap] library).
-
-For example:
-
-* `{3,3,0,6}` indicates:
-** a left column of properties taking up 25% of the width
-** a middle column of properties taking up 25% of the width
-** a right column of collections taking up 50% of the width
-* `{2,6,0,4}` indicates:
-** a left column of properties taking up ~16% of the width
-** a middle column of properties taking up 50% of the width
-** a right column of collections taking up ~33% of the width
-* `{2,3,3,4}` indicates:
-** a left column of properties taking up ~16% of the width
-** a middle column of properties taking up 25% of the width
-** a right column of properties taking up 25% of the width
-** a far right column of collections taking up ~33% of the width
-
-If the sum of all the columns exceeds 12, then the collections are placed underneath the properties, taking up the full span. For example:
-
-* {4,4,4,12} indicates:
-** a left column of properties taking up ~33% of the width
-** a middle column of properties taking up ~33% of the width
-** a right column of properties taking up ~33% of the width
-** the collections underneath the property columns, taking up the full width
-
-== Example Layouts
-
-Below are sketches for the layout of the https://github.com/apache/isis/blob/f38fdb92941172eabb12e0943509f239e6d5925f/example/application/quickstart_wicket_restful_jdo/dom/src/main/java/dom/todo/ToDoItem.java[ToDoItem] class of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
-
-The first divides the properties into two equal sized columns (6-6-0) and puts the collections underneath (12):
-
-image::{_imagesdir}reference-layout/6-6-0-12.png[width="720px",link="{_imagesdir}reference-layout/6-6-0-12.png"]
-
-The next divides the collections into three equal sized columns (4-4-4) and again puts the collections underneath (12):
-
-image::{_imagesdir}reference-layout/4-4-4-12.png[width="720px",link="{_imagesdir}reference-layout/4-4-4-12.png"]
-
-The last puts the properties into a single column (4-0) and places the collections into the other larger column (8-0):
-
-image::{_imagesdir}reference-layout/4-0-8-0.png[width="720px",link="{_imagesdir}reference-layout/4-0-8-0.png"]
-
-
-== Other Annotations
-
-As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: xref:rgant.adoc#_rgant-ActionLayout, [`@ActionLayout`] xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`], xref:rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`], xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], and xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring.adoc
deleted file mode 100644
index d041992..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ugodn_configuring]]
-= Configuring DataNucleus
-: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/
-
-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.
-
-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.adoc#_ugbtb_other-techniques_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-
-
-include::_ugodn_configuring_properties.adoc[leveloffset=+1]
-include::_ugodn_configuring_persistence-xml.adoc[leveloffset=+1]
-include::_ugodn_configuring_eagerly-registering-entities.adoc[leveloffset=+1]
-include::_ugodn_configuring_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::_ugodn_configuring_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index a922c35..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[_ugodn_configuring_disabling-persistence-by-reachability]]
-= Persistence by Reachability
-: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/
-
-By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if
-a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Apache Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-However, convenient though this feature is, you may find that it causes performance issues.
-
-[WARNING]
-====
-DataNucleus' persistence-by-reachability may cause performance issues. We strongly recommend that you disable it.
-====
-
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
-
-We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-This change has been made to the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
-
-If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
-
-
-
-
-
-== The issue in more detail
-
-Consider these entities (http://yuml.me/edit/b8681268[yuml.me/b8681268]):
-
-image::{_imagesdir}runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png[width="750px"]
-
-
-
-In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it.
-
-All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is:
-
-[source,java]
-----
-public class AgreementRole {
- ...
- public int compareTo(AgreementRole other) {
- return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
- }
-}
-----
-
-while ``Agreement``'s is implemented as:
-
-[source,java]
-----
-public class Agreement {
- ...
- public int compareTo(Agreement other) {
- return ObjectContracts.compareTo(this, other, "reference");
- }
-}
-----
-
-and ``Party``'s is similarly implemented as:
-
-[source,java]
-----
-public class Party {
- ...
- public int compareTo(Party other) {
- return ObjectContracts.compareTo(this, other, "reference");
- }
-}
-----
-
-DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
-
-* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
-
-* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
-
-* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
-
-In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_eagerly-registering-entities.adoc
deleted file mode 100644
index 68ade59..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugodn_configuring_eagerly-registering-entities]]
-= Eagerly Registering Entities
-: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/
-
-
-
-Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Apache Isis builds its metamodel by walking the graph of types of the domain services. The JDO/DataNucleus objectstore then takes these types and registers them with DataNucleus.
-
-In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.
-
-Apache Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating). In any case, it's probably not good practice to have DataNucleus work this way.
-
-The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly. In fact there are two:
-
-* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
-
-* for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified. To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`. (This is also supported in 1.9.0 if no `AppManifest` is specified. For integration testing this can be specified programatically.
-
-Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the xref:ugtst.adoc#_ugtst_integ-test-support_bootstrapping[user guide].
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_persistence-xml.adoc
deleted file mode 100644
index 91109d9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_persistence-xml.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ugodn_configuring_persistence-xml]]
-= `persistence.xml`
-: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: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_properties.adoc
deleted file mode 100644
index 56c92c8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_properties.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_ugodn_configuring_properties]]
-= Configuration Properties
-: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/
-
-
-These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-== Configuration Properties for Apache Isis itself
-
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.` +
-`datanucleus.` +
-`classMetadataLoadedListener`
-|`FQCN`
-|The default (`o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata`) creates a DB schema object
-
-
-|`isis.persistor.datanucleus.` +
-`RegisterEntities.packagePrefix`
-|fully qualified package names (CSV)
-|that specifies the entities early rather than allow DataNucleus to find the entities lazily. Further xref:ugodn.adoc#_ugodn_configuring_eagerly-registering-entities[discussion below].
-
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
-
-
-|`isis.persistor.datanucleus.` +
-`PublishingService.serializedForm`
-| zipped
-|
-
-|===
-
-
-
-== Configuration Properties passed through directly to DataNucleus.
-
-.JDO/DataNucleus Objectstore Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.persistor.datanucleus.impl.*`
-|
-| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.persistenceByReachabilityAtCommit`
-|`false`
-|We recommend this setting is disabled. +
-Further xref:ugodn.adoc#_ugodn_configuring_disabling-persistence-by-reachability[discussion below].
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_using-jndi-data-source.adoc
deleted file mode 100644
index 1d264e7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_configuring_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_ugodn_configuring_using-jndi-data-source]]
-= Using JNDI DataSource
-: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/
-
-Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
-
-
-
-== Application managed
-
-Using a connection pool managed directly by the application (that is, by Apache Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified.
-
-In either `WEB-INF\isis.properties` file (or `WEB-INF\persistor.properties`, or `WEB-INF\persistor_datanucleus.properties`), specify the connection driver, url, username and password.
-
-For example:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
-----
-
-Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-It is also possible to specify the `
-datanucleus.ConnectionPasswordDecrypter
-` property; see the link:http://www.datanucleus.org/products/accessplatform_4_1/persistence_properties.html#ConnectionPasswordDecrypter[DataNucleus documentation] for further details.
-
-
-
-
-== Container managed (JNDI)
-
-Using a datasource managed by the servlet container requires three separate bits of configuration.
-
-Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
-
-If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
-
-Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
-
-[source,xml]
-----
-<resource-ref>
- <description>db</description>
- <res-ref-name>jdbc/simpleapp</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-----
-
-Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`:
-
-[source,xml]
-----
-<Resource name="jdbc/simpleapp"
- auth="Container"
- type="javax.sql.DataSource"
- maxActive="100"
- maxIdle="30"
- maxWait="10000"
- username="sa"
- password="p4ssword"
- driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
- url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/>
-----
-
-You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`.
-
-[NOTE]
-====
-According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only. I was unable to get this working, however.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_java8.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_java8.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_java8.adoc
deleted file mode 100644
index 87fa0cd..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_java8.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugodn_java8]]
-= Java8
-: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/
-
-
-
-DataNucleus 4.x supports Java 7, but can also be used with Java 8, eg for streams support against collections managed
-by DataNucleus.
-
-Just include within `<dependencies>` of your `dom` module's `pom.xml`:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-java8</artifactId>
- <version>4.2.0-release</version>t
-</dependency>
-----
-
-[NOTE]
-====
-The DataNucleus website includes a link:http://www.datanucleus.org/products/accessplatform/compatibility.html[page]
-listing version compatibility of these extensions vis-a-vis the core DataNucleus platform.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc
deleted file mode 100644
index 908bb6f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ugodn_jdo-mappings]]
-= JDO Mappings
-: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/
-
-
-
-
-include::_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc
deleted file mode 100644
index 6c7ab01..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc
+++ /dev/null
@@ -1,321 +0,0 @@
-[[_ugodn_jdo-mappings_1-to-m-bidirectional-relationships]]
-= 1-m Bidirectional relationships
-: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/
-
-
-
-Consider a bidirectional one-to-many association between two entities; a collection member in the "parent" and a property member on the "child".
-
-We can tell DataNucleus about the bidirectionality using `@Persistent(mappedBy=...)`, or we can take responsibility for
-this aspect ourselves.
-
-In addition, the two entities can be associated either without or with a join table (indicated by the `@Join` annotation):
-
-* without a join table is more common; a regular foreign key in the child table for `FermentationVessel` points back up to the associated parent `Batch`
-* with a join table; a link table holds the tuple representing the linkage.
-
-Testing (as of `1.13.0`, against `dn-core 4.1.7`/`dn-rdbms 4.1.9`) has determined there are two main rules:
-
-* If not using `@Join`, then the association must be maintained by setting the child association on the parent. +
-+
-It is not sufficient to simply add the child object to the parent's collection.
-
-* `@Persistent(mappedBy=...)` and `@Join` cannot be used together. +
-+
-Put another way, if using `@Join` then you must maintain both sides of the relationship in the application code.
-
-
-In the examples that follow, we use two entities, `Batch` and `FermentationVessel` (from a brewery domain). In the
-original example domain the relationship between these two entities was optional (a `FermentationVessel` may
-have either none or one `Batch` associated with it); for the purpose of this article we'll explore both mandatory and
-optional associations.
-
-== Mandatory, no `@Join`
-
-In the first scenario we have use `@Persistent(mappedBy=...)` to indicate a bidirectional association, without any `@Join`:
-
-[source,java]
-----
-public class Batch {
-
- // getters and setters omitted
-
- @Persistent(mappedBy = "batch", dependentElement = "false") // <1>
- private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>();
-}
-----
-<1> "mappedBy" means this is bidirectional
-
-and
-
-[source,java]
-----
-public class FermentationVessel implements Comparable<FermentationVessel> {
-
- // getters and setters omitted
-
- @Column(allowsNull = "false") // <1>
- private Batch batch;
-
- @Column(allowsNull = "false")
- private State state; // <2>
-}
-----
-<1> mandatory association up to parent
-<2> State is an enum (omitted)
-
-
-Which creates this schema:
-
-[source,sql]
-----
-CREATE TABLE "batch"."Batch"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- ...
- "version" BIGINT NOT NULL,
- CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "fvessel"."FermentationVessel"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- "batch_id_OID" BIGINT NOT NULL,
- "state" NVARCHAR(255) NOT NULL,
- ...
- "version" TIMESTAMP NOT NULL,
- CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
-)
-----
-
-That is, there is an mandatory foreign key from `FermentationVessel` to `Batch`.
-
-
-In this case we can use this code:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-
-This sets up the association correctly, using this SQL:
-
-[source,sql]
-----
-UPDATE "fvessel"."FermentationVessel"
- SET "batch_id_OID"=\<0>
- ,"state"=<'FERMENTING'>
- ,"version"=<2016-07-07 12:37:14.968>
- WHERE "id"=\<0>
-----
-
-
-The following code will also work:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- getVessels().add(vessel); // <2>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-<2> add the child to the parent's collection.
-
-However, obviously the second statement is redundant.
-
-
-== Optional, no `@Join`
-
-If the association to the parent is made optional:
-
-[source,java]
-----
-public class FermentationVessel implements Comparable<FermentationVessel> {
-
- // getters and setters omitted
-
- @Column(allowsNull = "true") // <1>
- private Batch batch;
-
- @Column(allowsNull = "false")
- private State state;
-}
-----
-<1> optional association up to parent
-
-
-Which creates this schema:
-
-[source,sql]
-----
-CREATE TABLE "batch"."Batch"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- ...
- "version" BIGINT NOT NULL,
- CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "fvessel"."FermentationVessel"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- "batch_id_OID" BIGINT NULL,
- "state" NVARCHAR(255) NOT NULL,
- ...
- "version" TIMESTAMP NOT NULL,
- CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
-)
-----
-
-This is almost exactly the same, except the foreign key from `FermentationVessel` to `Batch` is now nullable.
-
-
-In this case then setting the parent on the child still works:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-
-*HOWEVER*, if we (redundantly) update both sides, then - paradoxically - the association is NOT set up
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- getVessels().add(vessel); // <2>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-<2> add the child to the parent's collection.
-
-[NOTE]
-====
-It's not clear if this is a bug in `dn-core 4.1.7`/`dn-rdbms 4.19`; an earlier thread on the mailing list from 2014 actually gave
-the opposite advice, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] and in particular this http://markmail.org/message/hblptpw675mlw723[message].
-
-In fact we also have http://markmail.org/message/agnwmzocvdfht32f[a different case] which argues that the parent
-should only be set on the child, and the child _not_ added to the parent's collection. This concurs with the most recent testing.
-====
-
-Therefore, the simple advice is that, for bidirectional associations, simply set the parent on the child, and this will work
-reliably irrespective of whether the association is mandatory or optional.
-
-
-== With `@Join`
-
-Although DataNucleus does not complain if `@Persistence(mappedBy=...)` and `@Join` are combined, testing (against `dn-core 4.1.7`/`dn-rdbms 4.19`) has shown that the bidirectional association is not properly maintained.
-
-Therefore, we recommend that if `@Join` is used, then manually maintain both sides of the relationship and do not indicate
-that the association is bidirectional.
-
-For example:
-
-[source,java]
-----
-public class Batch {
-
- // getters and setters omitted
-
- @Join(table = "Batch_vessels")
- @Persistent(dependentElement = "false")
- private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>();
-}
-----
-
-and
-
-[source,java]
-----
-public class FermentationVessel implements Comparable<FermentationVessel> {
-
- // getters and setters omitted
-
- @Column(allowsNull = "true") // <1>
- private Batch batch;
-
- @Column(allowsNull = "false")
- private State state;
-}
-----
-<1> optional association up to parent
-
-
-creates this schema:
-
-[source,sql]
-----
-CREATE TABLE "batch"."Batch"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- ...
- "version" BIGINT NOT NULL,
- CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "fvessel"."FermentationVessel"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- "state" NVARCHAR(255) NOT NULL,
- ...
- "version" TIMESTAMP NOT NULL,
- CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "batch"."Batch_vessels"
-(
- "id_OID" BIGINT NOT NULL,
- "id_EID" BIGINT NOT NULL,
- CONSTRAINT "Batch_vessels_PK" PRIMARY KEY ("id_OID","id_EID")
-)
-----
-
-That is, there is NO foreign key from `FermentationVessel` to `Batch`, instead the `Batch_vessels` table links the two together.
-
-
-These should then be maintained using:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- getVessels().add(vessel); // <2>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-<2> add the child to the parent's collection.
-
-
-that is, explicitly update both sides of the relationship.
-
-This generates this SQL:
-
-[source,sql]
-----
-INSERT INTO "batch"."Batch_vessels" ("id_OID","id_EID") VALUES (<0>,<0>)
-UPDATE "batch"."Batch"
- SET "version"=\<3>
- WHERE "id"=\<0>
-UPDATE "fvessel"."FermentationVessel"
- SET "state"=<'FERMENTING'>
- ,"version"=<2016-07-07 12:49:21.49>
- WHERE "id"=\<0>
-----
-
-
-It doesn't matter in these cases whether the association is mandatory or optional; it will be the same SQL generated.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugodn_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_overriding-jdo-annotations.adoc
deleted file mode 100644
index 07c1bd7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugodn_overriding-jdo-annotations.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ugodn_overriding-jdo-annotations]]
-= Overriding JDO Annotations
-: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/
-
-
-
-The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.
-
-For example, as of 1.9.0 the various http://www.isisaddons.org[Isis addons] modules (not ASF) use schemas for each entity. For example, the `AuditEntry` entity in the http://github.com/isisaddons/isis-module-audit[audit module] is annotated as:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(
- identityType=IdentityType.DATASTORE,
- schema = "IsisAddonsAudit",
- table="AuditEntry")
-public class AuditEntry {
- ...
-}
-----
-
-This will map the `AuditEntry` class to a table `"IsisAddonsAudit"."AuditEntry"`; that is using a custom schema to own the object.
-
-Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" ?>
-<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
- http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd" version="3.0">
- <package name="org.isisaddons.module.audit.dom">
- <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
- </class>
- </package>
-</jdo>
-----
-
-This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module.
-
-[TIP]
-====
-You can use a mixin action on xref:rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
-to download the JDO class metadata in XML form.
-====
-
-
-[NOTE]
-====
-* The same approach should work for any other JDO metadata, but some experimentation might be required.+
-+
-For example, in writing up the above example we found that writing `schema=""` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead.
-
-* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
-
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_ugbtb_decoupling_db-schemas[using modules].
-
-* You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
-====
-
-