You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/13 10:38:02 UTC
[23/50] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to
ugfun.adoc. Added standard section to each of the guides so can navigate
between each easily.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
deleted file mode 100644
index c77328c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
+++ /dev/null
@@ -1,304 +0,0 @@
-[[_ug_getting-started_simpleapp-archetype]]
-= SimpleApp Archetype
-: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 quickest way to get started with Apache Isis is to run the simple archetype. This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`.
-
-There is also a corresponding `SimpleObjectRepository` domain service. From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
-
-
-
-== Generating the App
-
-Create a new directory, and `cd` into that directory.
-
-To build the app from the latest stable release, then run the following command:
-
-[source,bash]
-----
-mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.10.0 \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -B
-----
-
-where:
-
-- `groupId` represents your own organization, and
-- `artifactId` is a unique identifier for this app within your organization.
-- `version` is the initial (snapshot) version of your app
-
-The archetype generation process will then run; it only takes a few seconds.
-
-
-We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
-
-The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
-
-[source,bash]
-----
-mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.11.0-SNAPSHOT \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
- -B
-----
-
-where as before:
-
-- `groupId` represents your own organization, and
-- `artifactId` is a unique identifier for this app within your organization.
-- `version` is the initial (snapshot) version of your app
-
-but also:
-
-- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
-- `archetypeRepository` specifies the location of our snapshot repo (hosted on link:http://www.cloudbees.com[CloudBees]), and
-
-The archetype generation process will then run; it only takes a few seconds.
-
-
-
-== Building the App
-
-Switch into the root directory of your newly generated app, and build your app:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-where `myapp` is the `artifactId` entered above.
-
-
-
-
-== Running the App
-
-The `simpleapp` archetype generates a single WAR file, configured to run both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer]. The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
-
-Once you've built the app, you can run the WAR in a variety of ways.
-
-
-=== Self-hosted
-
-The easiest way to run the app, at least while getting started, is to run the self-hosting version of the WAR. With this style the app runs up its own internal instance of Jetty web server.
-
-For example:
-
-
-[source,bash]
-----
-java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar
-----
-
-
-This can also be accomplished using an embedded Ant target provided in the build script:
-
-[source,bash]
-----
-mvn -P self-host antrun:run
-----
-
-
-=== Using mvn Jetty plugin
-
-Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
-
-[source,bash]
-----
-cd webapp
-mvn jetty:run
-----
-
-If you use `mvn jetty:run`, then the context path changes; check the console output (eg link:http://localhost:8080/myapp-webapp [http://localhost:8080/myapp-webapp]).
-
-
-You can also provide a system property to change the port:
-
-[source,bash]
-----
-cd webapp
-mvn jetty:run -D jetty.port=9090
-----
-
-
-=== Using a regular servlet container
-
-You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](http://tomcat.apache.org). The default configuration does not require any configuration of the servlet container; just drop the WAR file into the `webapps` directory.
-
-
-
-=== From within the IDE
-
-Most of the time, though, you'll probably want to run the app from within your IDE. The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA. Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
-
-Here's what the setup looks like in IntelliJ IDEA:
-
-image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp.png"]
-
-
-
-== Running with Fixtures
-
-It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing. This is done by specifying a xref:ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
-
-If running the self-hosted console, you can specify the fixtures using the `--initParam` flag:
-
-[source,bash]
-----
-java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
- --initParam isis.persistor.datanucleus.install-fixtures=true \
- --initParam isis.fixtures=domainapp.fixture.scenarios.RecreateSimpleObjects
-----
-
-where (in the above example) `domainapp.fixture.scenarios.RecreateSimpleObjects` is the fully qualified class name of the fixture
-script to be run.
-
-If you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag:
-
-image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
-
-
-
-== Using the App
-
-When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[Restful Objects viewer]:
-
-image::{_imagesdir}getting-started/using-simple-app/010-root-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/010-root-page.png"]
-
-
-The Wicket viewer provides a human usable web UI (implemented, as you might have guessed from its name, using link:http://wicket.apache.org[Apache Wicket]), so choose that and navigate to the login page:
-
-image::{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png"]
-
-The app itself is configured to run using xref:ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file. You can login with:
-
-* username: _sven_
-* password: _pass_
-
-The application is configured to run with an in-memory database, and (unless you started the app with fixture scripts as described above), initially there is no data. We can though run a fixture script from the app itself:
-
-image::{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/030-home-page-run-fixture-scripts.png"]
-
-The fixture script creates three objects, and the action returns the first of these:
-
-image::{_imagesdir}getting-started/using-simple-app/040-first-object.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/040-first-object.png"]
-
-The application generated is deliberaetly very minimal; we don't want you to have to waste valuable time removing generated files. The object contains a single "name" property, and a single action to update that property:
-
-image::{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/050-update-name-prompt.png"]
-
-When you hit OK, the object is updated:
-
-image::{_imagesdir}getting-started/using-simple-app/060-object-updated.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/060-object-updated.png"]
-
-
-For your most signficant domain entities you'll likely have a domain service to retrieve or create instances of those obejcts. In the generated app we have a "Simple Objects" domain service that lets us list all objects:
-
-image::{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/070-list-all-prompt.png"]
-
-whereby we see the three objects created by the fixture script (one having been updated):
-
-image::{_imagesdir}getting-started/using-simple-app/080-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/080-list-all.png"]
-
-and we can also use the domain service to create new instances:
-
-image::{_imagesdir}getting-started/using-simple-app/090-create.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/090-create.png"]
-
-prompting us for the mandatory information (the name):
-
-image::{_imagesdir}getting-started/using-simple-app/100-create-prompt.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/100-create-prompt.png"]
-
-which, of course, returns the newly created object:
-
-image::{_imagesdir}getting-started/using-simple-app/110-object-created.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/110-object-created.png"]
-
-When we list all objects again, we can see that the object was indeed created:
-
-image::{_imagesdir}getting-started/using-simple-app/120-list-all.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/120-list-all.png"]
-
-Going back to the home page (link:http://localhost:8080[localhost:8080]) we can also access the Restful Objects viewer. The generated application is configured to use HTTP Basic Auth:
-
-image::{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/220-login-to-restful-viewer.png"]
-
-The Restful Objects viewer provides a REST API for computer-to-computer interaction, but we can still interact with it from a browser:
-
-image::{_imagesdir}getting-started/using-simple-app/230-home-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/230-home-page.png"]
-
-[TIP]
-====
-Depending on your browser, you may need to install plugins. For Chrome, we recommend json-view (which renders the JSON indented and automatically detects hyperlinks) and REST Postman.
-====
-
-The REST API is a complete hypermedia API, in other words you can follow the links to access all the behaviour exposed in the regular Wicket app. For example, we can navigate to the `listAll/invoke` resource:
-
-image::{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/240-list-all-invoke.png"]
-
-which when invoked (with an HTTP GET) will return a representation of the domain objects.
-
-image::{_imagesdir}getting-started/using-simple-app/250-list-all-results.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/250-list-all-results.png"]
-
-
-To log in, use `sven/pass`.
-
-
-
-
-
-== Modifying the App
-
-Once you are familiar with the generated app, you'll want to start modifying it. There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main link:../documentation.html[documentation] page first).
-
-If you use Eclipse or IntelliJ IDEA, do also install the xref:cg.adoc#_cg_ide-templates[IDE templates]; these will help you follow the Apache Isis naming conventions.
-
-
-
-
-
-== App Structure
-
-As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
-
-
-
-[cols="1,3", options="header"]
-|===
-| Module
-| Description
-
-|`myapp`
-|The parent (aggregator) module
-
-|`myapp-app`
-|(1.9.0) The "app" module, containing the (optional) app manifest and any application-level services.
-
-|`myapp-dom`
-|The domain object model, consisting of `SimpleObject` and `SimpleObjects` (repository) domain service.
-
-|`myapp-fixture`
-|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
-
-|`myapp-integtests`
-|End-to-end xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] that exercise from the UI through to the database
-
-|`myapp-webapp`
-|Run as a webapp (from `web.xml`) hosting the xref:ugvw.adoc#[Wicket viewer] and/or the xref:ugvro.adoc#[RestfulObjects viewer]
-
-|===
-
-
-
-If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
deleted file mode 100644
index 2ab5b65..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ug_how-tos]]
-= How tos
-: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/
-
-
-This chapter provides a grab bag of "how-to"s and tips to help you go about actually developing Apache Isis domain applications.
-
-include::_ug_how-tos_class-structure.adoc[leveloffset=+1]
-include::_ug_how-tos_ui-hints.adoc[leveloffset=+1]
-include::_ug_how-tos_domain-services.adoc[leveloffset=+1]
-include::_ug_how-tos_crud.adoc[leveloffset=+1]
-include::_ug_how-tos_entity-relationships.adoc[leveloffset=+1]
-include::_ug_how-tos_contributed-members.adoc[leveloffset=+1]
-include::_ug_how-tos_business-rules.adoc[leveloffset=+1]
-include::_ug_how-tos_derived-members.adoc[leveloffset=+1]
-include::_ug_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
-include::_ug_how-tos_bulk-actions.adoc[leveloffset=+1]
-include::_ug_how-tos_simulating-collections-of-values.adoc[leveloffset=+1]
-include::_ug_how-tos_render-all-properties-in-tables.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
deleted file mode 100644
index fa40181..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_how-tos_bulk-actions]]
-= Bulk Actions
-: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 - xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
deleted file mode 100644
index 71794c6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_how-tos_business-rules]]
-= Business Rules
-: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
-
-
-
-== Visibility ("see it")
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
-
-### Hide a Property
-
-### Hide a Collection
-
-### Hide an Action
-
-### Hide a Contributed Property, Collection or Action
-
-### All Members Hidden
-
-
-
-
-== Usability ("use it")
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
-
-### Disable a Property
-
-### Disable a Collection
-
-### Disable an Action
-
-### Disable a Contributed Property, Collection or Action
-
-### All Members Unmodifiable (Disabling the Edit Button)
-
-Sometimes an object is unmodifiable.
-
-In the Wicket viewer this means disabling the edit button.
-
-#### Declarative
-
-`@DomainObject(editing=...)`
-
-#### Imperative
-
-
-
-== Validity ("do it")
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
-
-
-### Validate (change to) a Property
-
-### Validate (adding or removing from) a Collection
-
-### Validate (arguments to invoke) an Action
-
-### Validating a Contributed Property, Collection or Action
-
-### Declarative validation
-
-NOTE: TODO - using xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
deleted file mode 100644
index fdd5061..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ug_how-tos_class-structure]]
-= Class Structure
-: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 works by building a metamodel of the domain objects: entities, xref:ugbtb.adoc#_ugbtb_more-advanced_view-models[view model]s and services. The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions. The class members of domain services is simpler: just behaviour, ie actions.
-
-In the automatically generated UI a property is rendered as a field. This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity. A collection is generally rendered as a table.
-
-In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_. This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
-
-Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
-
-In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
-
-[TIP]
-====
-In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax. The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
-
-You can learn more about extending Apache Isis programming model xref:ugbtb.adoc#_ugbtb_programming-model[here].
-====
-
-
-include::_ug_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_properties.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_collections.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_actions.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
-include::_ug_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
-
-include::_ug_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-
-include::_ug_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
deleted file mode 100644
index 1e7a0f8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_how-tos_class-structure_action-parameters]]
-= Action Parameters
-: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
-
-
-
-== ``String``s (Length)
-
-NOTE: TODO
-
-
-== ``BigDecimal``s (Precision)
-
-NOTE: TODO
-
-
-== Optional
-
-NOTE: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
deleted file mode 100644
index 5e29c34..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_how-tos_class-structure_actions]]
-= Actions
-: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
-
-
-[NOTE]
-====
-While Apache Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
-
-The workaround is to mark the collection as `@Programmatic`, as described in xref:ug.adoc#_ug_how-tos_class-structure_ignoring-methods[Ignoring Methods]. This ensures that the collection is ignored by Apache Isis.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index 444ff86..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ug_how-tos_class-structure_class-definition]]
-= Class Definition
-: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
-
-
-Classes are defined both to Isis and (if an entity) also to JDO/DataNucleus.
-
-
-We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then reason about all the classes in that package/namespace as a single unit.
-
-In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
-
-[TIP]
-====
-For more on this topic, see the topic discussing modules and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling[decoupling].
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
deleted file mode 100644
index 455144e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_how-tos_class-structure_collections]]
-= Collections
-: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
-
-
-[NOTE]
-====
-While Apache Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
-
-Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Apache Isis has no default visualization.
-
-One workaround is to mark the collection as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]. This ensures that the collection is ignored by Apache Isis.
-
-Another workaround is to wrap each value in a view model, as explained in this xref:ug.adoc#_ug_how-tos_simulating-collections-of-values[tip].
-====
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
deleted file mode 100644
index 9dcdae5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ug_how-tos_class-structure_ignoring-methods]]
-= Ignoring Methods
-: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
-
-
-Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Apache Isis' UI.
-
-To exclude such methods, use the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] annotation.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
deleted file mode 100644
index 3ca16a6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
+++ /dev/null
@@ -1,83 +0,0 @@
-[[_ug_how-tos_class-structure_inject-services]]
-= Injecting services
-: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 autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib `DomainObjectContainer` is also a service, so can be injected in exactly the same manner.
-
-
-[NOTE]
-====
-Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
-
-If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
-====
-
-
-== Field Injection
-
-Field injection is recommended, using the `@javax.inject.Inject` annotation. For example:
-
-[source,java]
-----
-public class Customer {
- @javax.inject.Inject
- OrderRepository orderRepository;
- ...
-}
-----
-
-
-We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
-
-
-
-
-== Method Injection
-
-Isis also supports two forms of method injection. All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
-of the method does not matter, only that it is prefixed either `set` or `inject`, is
-public, and has a single parameter of the correct type.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- private OrderRepository orderRepository;
- public void setOrderRepository(OrderRepository orderRepository) {
- this.orderRepository = orderRepository;
- }
- ...
-}
-----
-
-or alternatively, using 'inject' as the prefix:
-
-[source,java]
-----
-public class Customer {
- private OrderRepository orderRepository;
- public void injectOrderRepository(OrderRepository orderRepository) {
- this.orderRepository = orderRepository;
- }
- ...
-}
-----
-
-Note that the method name can be anything; it doesn't need to be related to the type being injected.
-
-
-
-
-== Constructor injection
-
-Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index 75184e1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_how-tos_class-structure_properties-vs-parameters]]
-= Properties vs Parameters
-: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
-
-
-In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`. Ideally we want the surname property and surname action parameter to use the same value type.
-
-Having first-class support for this is a goal of Apache Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal. However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as `java.lang.String`.
-
-However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters. It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
-
-The table below summarises the equivalence of some of the most common cases.
-
-
-.Comparing annotations of Properties vs Action Parameters
-[cols="2,3,3", options="header"]
-|===
-|value type/semantic
-|property
-|action parameter
-
-|string (length)
-|
-|
-
-|big decimal (precision)
-|
-|
-
-|Isis blob
-|
-|
-
-|optional
-|`@Column(allowsNull="true")`
-|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
-|===
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
deleted file mode 100644
index 5b5e983..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
+++ /dev/null
@@ -1,299 +0,0 @@
-[[_ug_how-tos_class-structure_properties]]
-= Property
-: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
-
-
-
-
-
-== Value vs Reference Types
-
-NOTE: TODO
-
-The annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties. The table in the xref:ug.adoc#_ug_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
-
-
-
-== Optional Properties
-
-JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc). To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
-
-Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional. These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`.
-
-These different defaults can lead to incompatibilities between the two frameworks. To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
-
-For example, rather than:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowNulls="true")
-private LocalDate date;
-@Property(optionality=Optionality.OPTIONAL)
-public LocalDate getDate() { ... }
-public void setDate(LocalDate d) { ... }
-----
-
-you should instead simply write:
-
-[source,java]
-----
-private LocalDate date;
-@javax.jdo.annotations.Column(allowNulls="true")
-public LocalDate getDate() { ... }
-public void setDate(LocalDate d) { ... }
-----
-
-[WARNING]
-====
-With JDO/DataNucleus it's valid for the `@Column` annotation to be placed on either the field or the getter. Apache Isis (currently) only looks for annotations on the getter. We therefore recommend that you always place `@Column` on the gettter.
-====
-
-In all cases the framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
-
-
-
-=== Handling Mandatory Properties in Subtypes
-
-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 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 {
- private LocalDate date;
- @javax.jdo.annotations.Column(allowNulls="true")
- @Property(optionality=Optionality.MANDATORY)
- public LocalDate getDate() { ... }
- public void setDate(LocalDate d) { ... }
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations. Its benefit is that it lumps together all Apache Isis' property metadata in a single annotation. Its downside is that it is rather verbose if the only semantic that needs to be specified -- as is often the case -- is optionality.
-====
-
-An alternative way to achieve this is to leave the JDO annotation on the field (where it is invisible to Apache Isis), and rely on Isis' default, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
- @javax.jdo.annotations.Column(allowNulls="true")
- private LocalDate date;
- // mandatory in Apache Isis by default
- public LocalDate getDate() { }
- public void setDate(LocalDate d) { }
-}
-----
-
-We recommend the former mapping, though, using `@Property(optionality=Optionality.MANDATORY)`.
-
-
-
-
-
-== ``String``s (Length)
-
-NOTE: TODO
-
-
-
-
-
-[[_ug_how-tos_class-structure_properties_mapping-joda-dates]]
-== Mapping JODA Dates
-
-Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
-
-It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted. See the http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
-
-Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute. To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
-
-For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
-
-
-
-== ``BigDecimal``s (Precision)
-
-Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
-
-For example, suppose we have:
-
-[source,java]
-----
-private BigDecimal impact;
-public BigDecimal getImpact() {
- return impact;
-}
-public void setImpact(final BigDecimal impact) {
- this.impact = impact;
-}
-----
-
-JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
-
-What this implies is that, when a record is inserted, a log entry similar to this one appears:
-
-[source,java]
-----
-INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
-----
-
-But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
-
-The solution is to explicitly add the scale to the field like this:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)
-private BigDecimal impact;
-public BigDecimal getImpact() {
- return impact;
-}
-public void setImpact(final BigDecimal impact) {
- this.impact = impact;
-}
-----
-
-In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
-
-More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
-
-
-
-
-== Mapping Blobs and Clobs
-
-Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
-
-As for xref:ug.adoc#_ug_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
-
-=== Mapping Blobs
-
-For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/61b8114a8e01dbb3c380b31cf09eaed456407570/dom/src/main/java/todoapp/dom/module/todoitem/ToDoItem.java#L475[todoapp example app] (non-ASF) the `attachment` property is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "attachment_name"),
- @javax.jdo.annotations.Column(name = "attachment_mimetype"),
- @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
-})
-private Blob attachment;
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Blob getAttachment() {
- return attachment;
-}
-public void setAttachment(final Blob attachment) {
- this.attachment = attachment;
-}
-----
-
-The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns. (It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
-
-If the `Blob` is mandatory, then use:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
- @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
- @javax.jdo.annotations.Column(name = "attachment_bytes",
- jdbcType="BLOB", sqlType = "LONGVARBINARY",
- allowsNull="false")
-})
-private Blob attachment;
-@Property(
- optionality = Optionality.MANDATORY
-)
-public Blob getAttachment() {
-return attachment;
-}
-public void setAttachment(final Blob attachment) {
-this.attachment = attachment;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB". There can be differences in behaviour between JDBC drivers.
-====
-
-
-=== Mapping Clobs
-
-Mapping `Clob`s works in a very similar way, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "attachment_name"),
- @javax.jdo.annotations.Column(name = "attachment_mimetype"),
- @javax.jdo.annotations.Column(name = "attachment_chars",
- jdbcType="CLOB", sqlType = "LONGVARCHAR")
-})
-private Clob doc;
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() {
- return doc;
-}
-public void setDoc(final Clob doc) {
- this.doc = doc;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB". There can be differences in behaviour between JDBC drivers.
-====
-
-=== Mapping to VARBINARY or VARCHAR
-
-Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`. The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
-
-For example:
-
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
-----
-
-
-The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
-
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
-----
-
-Support and maximum allowed length will vary by database vendor.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
deleted file mode 100644
index 7763490..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[_ug_how-tos_contributed-members]]
-= Contributed Members
-: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 - generalize to discussion on contributed collections/properties; update to new annotations
-
-Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
-
-For example, given a service:
-
-[source,java]
-----
-public interface Library {
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source,java]
-----
-public class Book implements Loanable { ... }
-----
-
-and
-
-[source,java]
-----
-public class LibraryMember implements Borrower { ... }
-----
-
-then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
-
-This is an important capability because it helps to decouple the concrete classes from the services.
-
-If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
- @NotContributed
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
-
-Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-
-## Contributed Action
-
-NOTE: TODO
-
-## Contributed Property
-
-NOTE: TODO
-
-## Contributed Collection
-
-NOTE: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
deleted file mode 100644
index 353f468..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_how-tos_crud]]
-= Object Management (CRUD)
-: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
-
-
-## Instantiating and Persisting Objects
-
-NOTE: TODO - using ``DomainObjectContainer``'s support for xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-creation-api[creation] and xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[persistence]
-
-## Finding Objects
-
-NOTE: TODO - using xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-
-### Using DataNucleus type-safe queries
-
-NOTE: TODO - as described xref:rgsvc.adoc#_rgsvc-api_IsisJdoSupport_type-safe-jdoql-queries[here]
-
-
-
-## Deleting Objects
-
-NOTE: TODO using ``DomainObjectContainer``'s support for xref:rgsvc.adoc#_rgsvc-api_DomainObjectContainer_object-persistence-api[persistence]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
deleted file mode 100644
index dea0b06..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ug_how-tos_derived-members]]
-= Derived Members
-: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
-
-
-
-
-== Derived Property
-
-NOTE: TODO
-
-
-
-
-== Derived Collection
-
-NOTE: TODO
-
-While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- ...
- public List<Order> getMostRecentOrders() {
- return orderRepo.findMostRecentOrders(this, 5);
- }
-}
-----
-
-
-
-
-== Trigger on property change
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
-
-
-
-== Trigger on collection change
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
deleted file mode 100644
index eea9859..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
+++ /dev/null
@@ -1,313 +0,0 @@
-[[_ug_how-tos_domain-services]]
-= Domain Services
-: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/
-
-
-
-
-In Apache Isis domain services have several responsibilities:
-
-- to expose actions to be rendered in the menu
-- to provide actions that are rendered as contributed actions/properties/collections on the contributee domain object
-- they act as subscribers to the event bus
-- they act as repositories (find existing objects) or as factories (create new objects)
-- they provide other services (eg performing calculations, attach a barcode, send an email etc).
-- to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
-
-It's worth extending the xref:ug.adoc#_ug_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
-
-.The hexagonal architecture with Isis addons
-image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
-
-The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings). Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
-
-The Apache Isis framework also provides numerous in-built domain services. These are catalogued in the reference guide, see xref:rgsvc.adoc#_rgsvc-api[here] and xref:rgsvc.adoc#_rgsvc-spi[here].
-
-
-
-[[_ug_how-tos_domain-services_organizing-services]]
-== Organizing Services
-
-In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
-
-The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
-
-- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
-- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
-- `VIEW_CONTRIBUTED_ONLY` indicates that the actions should appear on the menu
-- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
-
-Pulling all the above together, here are our suggestions as to how you should organize your domain services.
-
-
-=== Factory and Repository
-
-The factory/repository uses an injected `DomainObjectContainer` to both instantiate new objects and to query the database for existing objects of a given entity type. It is not visible in UI, rather other services delegate to it.
-
-We suggest naming such classes `XxxRepository`, eg:
-
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN // <1>
-)
-public CustomerRepository {
- public List<Customer> findCustomerBy...(...) {
- return allMatches(...);
- }
- public Customer newCustomer(...) {
- Customer Customer = container.newTransientInstance(Customer.class);
- ...
- persistIfNotAlready(Customer);
- return Customer;
- }
- public List<Customer> allCustomers() {
- return container.allInstances(Customer.class);
- }
- @Inject
- DomainObjectContainer container;
-}
-----
-<1> interacted with only programmatically by other objects in the domain layer.
-
-There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
-
-
-
-=== Menu
-
-Menu services provide actions to be rendered on the menu.
-
-For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer. It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
-
-For the Restful Objects viewer, all menu services are shown in the services representation.
-
-We suggest naming such classes `XxxMenu`, eg:
-
-
-[source,java]
-----
-@DomainService(
- nature = NatureOfService.VIEW_MENU_ONLY // <1>
-)
-@DomainServiceLayout(
- named = "Customers", // <2>
- menuBar = DomainServiceLayout.MenuBar.PRIMARY,
- menuOrder = "10"
-)
-public class CustomerMenu {
- @Action(
- semantics = SemanticsOf.SAFE
- )
- @MemberOrder( sequence = "1" )
- public List<Customer> findCustomerBy...(...) {
- return CustomerRepository.findCustomerBy(...); // <3>
- }
-
- @Action(
- semantics = SemanticsOf.NON_IDEMPOTENT
- )
- @MemberOrder( sequence = "3" )
- public Customer newCustomer(...) {
- return CustomerRepository.newCustomer(...);
- }
-
- @Action(
- semantics = SemanticsOf.SAFE,
- restrictTo = RestrictTo.PROTOTYPING
- )
- @MemberOrder( sequence = "99" )
- public List<Customer> allCustomers() {
- return CustomerRepository.allBankMandates();
- }
-
- @Inject
- protected CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be rendered as menu items
-<2> specifies the menu name. All services with the same menu name will be displayed on the same menu, with separators between
-<3> delegates to an injected repository.
-
-Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
-
-[TIP]
-====
-Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it. Instead, inject the underlying repository. If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
-====
-
-
-
-=== Contributions
-
-Services can contribute either actions, properties or collections, based on the type of their parameters.
-
-We suggest naming such classes `XxxContributions`, eg:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY // <1>
-)
-@DomainServiceLayout(
- menuOrder="10",
- name="...",
-}
-public OrderContributions {
- @Action(semantics=SemanticsOf.SAFE)
- @ActionLayout(contributed=Contributed.AS_ASSOCIATION) // <2>
- @CollectionLayout(render=RenderType.EAGERLY)
- public List<Order> orders(Customer customer) { // <3>
- return container.allMatches(...);
- }
-
- @Inject
- CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be contributed to the entities of the parameters of those actions
-<2> contributed as an association, in particular as a collection because returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found xref:ug.adoc#_ug_how-tos_contributed-members[here]. More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_contributions[here] and xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_mixins[here].
-
-
-=== Event Subscribers
-
-Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
-
-We suggest naming such classes `XxxSubscriptions`, eg:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN // <1>
-)
-@DomainServiceLayout(
- menuOrder="10",
- name="...",
-}
-public CustomerOrderSubscriptions {
- @com.google.common.eventbus.Subscribe
- public void on(final Customer.DeletedEvent ev) {
- Customer customer = ev.getSource();
- orderRepository.delete(customer);
- }
- @Inject
- OrderRepository orderRepository;
-}
-----
-<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
-
-
-
-== Prototyping
-
-While for long-term maintainability we do recommend the naming conventions described xref:ug.adoc#_ug_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
-
-If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
-appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
-
-Later on it is easy enough to refactor the code to tease apart the different responsibilities.
-
-
-
-
-== Scoped services
-
-By default all domain services are considered to be singletons, and thread-safe.
-
-Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
-
-The CDI annotation xref:rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
-
-[source,java]
-----
-@javax.enterprise.context.RequestScoped
-public class MyService extends AbstractService {
- ...
-}
-----
-
-The framework provides a number of request-scoped services, include a scratchpad service, query results caching, and support for co-ordinating bulk actions. See xref:rgsvc.adoc#_rgsvc-api[here] and xref:rgsvc.adoc#_rgsvc-spi[here] for further details.
-
-
-
-
-== Registering domain services
-
-The easiest way to register domain services is using xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
-which contain xref:rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
-
-For example:
-
-[source,ini]
-----
-public class MyAppManifest implements AppManifest {
- public List<Class<?>> getModules() {
- return Arrays.asList(
- ToDoAppDomainModule.class,
- ToDoAppFixtureModule.class,
- ToDoAppAppModule.class,
- org.isisaddons.module.audit.AuditModule.class);
- }
- ...
-}
-----
-
-will load all services in the packages underneath the four modules listed.
-
-An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
-
-[source,ini]
-----
-isis.services = com.mycompany.myapp.employee.Employees\,
- com.mycompany.myapp.claim.Claims\,
- ...
-----
-
-This will then result in the framework instantiating a single instance of each of the services listed.
-
-If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
-
-[source,ini]
-----
-isis.services.prefix = com.mycompany.myapp
-isis.services = employee.Employees,\
- claim.Claims,\
- ...
-----
-
-This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
-
-Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:rgsvc.adoc#_rgsvc-api[here] and _rgsvc-spi[here] for further details.
-
-
-
-
-== Initialization
-
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
-
-An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
-
-
-The framework will call any `public` method annotated with xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
-
-or
-
-In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
-
-
-Shutdown is similar; the framework will call any method annotated with xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
-
-
-
-== The getId() method
-
-Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method. This method returns a logical identifier for a service, independent of its implementation.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
deleted file mode 100644
index 94891a7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_ug_how-tos_drop-downs-and-defaults]]
-= Drop Downs and Defaults
-: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
-
-
-== For Properties
-
-NOTE: TODO
-
-### Choices for Property
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for property
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for property
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-== For Action Parameters
-
-NOTE: TODO
-
-### Choices for action parameter
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Dependent choices for action params
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for action param
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for action param
-
-NOTE: TODO - xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-
-== For both Properties and Action Parameters
-
-NOTE: TODO
-
-
-### Drop-down for limited number of instances
-
-NOTE: TODO - xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
-
-
-### Auto-complete (repository-based)
-
-xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
deleted file mode 100644
index a41ad08..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_how-tos_entity-relationships]]
-= Entity 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/
-
-
-NOTE: TODO
-
-== Mandatory and Optional
-
-NOTE: TODO
-
-
-include::_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
deleted file mode 100644
index 0b1d64a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships]]
-= 1-m bidir 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/
-
-
-
-When an object is added to a 1:m bidirectional relationship, the child object must refer to the parent and the child must be added to the parent's children collection.
-
-If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly. (The xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
-
-However, in a relational database, these two operations in the domain object model correspond simply to updating the foreign key of the child table to reference the parent's primary key.
-
-So long as the parent's children collection is a `java.util.Set` (rather than a `Collection` or a `List`), the JDO Objectstore will automatically maintain both sides of the relationship. All that is necessary is to set the child to refer to the parent.
-
-For example, all you need write is:
-
-[source,java]
-----
-public class Department {
- @javax.jdo.annotations.Persistent(mappedBy="department") // <1>
- private SortedSet<Employee> employees = new TreeSet<Employee>();
-
- public SortedSet<Employee> getEmployees() { ... }
- public void setEmployees(SortedSet<Employee> employees) { ... }
- ...
-}
-public class Employee {
- private Department department;
- public Department getDepartment() { ... }
- public void setDepartment(Department department) { ... }
- ...
-}
-----
-<1> it's the `mappedBy` attribute that tells DataNucleus this is a bidirectional relationship. The value "department" refers to the Employee#department property.
-
-Moreover, when maintaining a bidirectional 1-n relationship that is automatically managed by DataNucleus, it's preferred to "add" to the parent's child collection, don't set the parent on the child.
-
-
-[WARNING]
-====
-If you don't do this then you may hit a `NullPointerException`. The above idiom fixes the issue.
-
-For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the Apache Isis users
-mailing list, including this http://markmail.org/message/hblptpw675mlw723[message] with the above recommendation.
-====
-
-
-[WARNING]
-====
-In fact, not only do you not need to manually maintain the relationship, we have noted on at least http://markmail.org/message/agnwmzocvdfht32f[one occasion] a subtle error if the code is programmatically added.
-
-The error in that case was that the same object was contained in the parents collection. This of course should not happen for a `TreeSet`. However, JDO/DataNucleus replaces the `TreeSet` with its own implementation, and (either by design or otherwise) this does not enforce `Set` semantics.
-
-The upshot is that you should NEVER programmatically add the child object to the parent's collection if using JDO Objectstore.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc
deleted file mode 100644
index 4b51613..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_render-all-properties-in-tables.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_how-tos_render-all-properties-in-tables]]
-= Subclass properties in tables
-: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/
-
-
-
-Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example:
-
-[source,java]
-----
-public abstract class LeaseTerm {
- public abstract BigDecimal getEffectiveValue();
- ...
-}
-
-public class LeaseTermForIndexableTerm extends LeaseTerm {
- public BigDecimal getEffectveValue() { ... }
- ...
-}
-----
-
-Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views).
-
-[NOTE]
-====
-For more background on this workaround, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582].
-====
-
-The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg:
-
-[source,java]
-----
-public abstract class LeaseTerm {
- public BigDecimal getEffectiveValue() {
- return null; // workaround for ISIS-582
- }
- ...
-}
-----
-
-
-Alternatively the implementation could throw a `RuntimeException`, eg
-
-[source,java]
-----
-throw new RuntimeException("never called; workaround for ISIS-582");
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc
deleted file mode 100644
index 32f38a2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_simulating-collections-of-values.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_how-tos_simulating-collections-of-values]]
-= Collections of values
-: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/
-
-
-
-Although in Apache Isis you can have properties of either values (string, number, date etc) or of (references to other) entities, with collections the framework (currently) only supports collections of (references to) entities. That is, collections of values (a bag of numbers, say) are not supported.
-
-However, it is possible to simulate a bag of numbers using view models.
-
-
-== View Model
-
-NOTE: TODO
-
-
-
-== Persistence Concerns
-
-NOTE: TODO - easiest to simply store using DataNucleus' support for collections, marked as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis. Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
-