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:57 UTC
[21/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_faqs_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
deleted file mode 100644
index 8a749c5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[_ugfun_faqs_how-to-handle-void-and-null-results]]
-= How to handle void/null results
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
-
-* _When using a void action, let\u2019s say a remove action, the user is redirected to a
-page "no results". When clicking the back button in the browser the user sees
-"Object not found" (since you\u2019ve just deleted this object)._
-
-* _You can return a list for example to prevent the user from being redirect to a
- "No results" page, but I think it\u2019s not the responsibility of the controllers in
- the domain model._
-
-* _A solution could be that wicket viewer goes back one page when
- encountering a deleted object. And refresh the current page when receiving a
- null response or invoking a void action. But how to implement this?_
-
-One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service. The default implementation will either return
-the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if
-one exists.
-
-The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the
-first non-deleted domain object found in the list of breadcrumbs:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@DomainServiceLayout(menuOrder = "1") // <1>
-public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
- @Override
- public Object route(final Object original) {
- if(original != null) { // <2>
- return original;
- }
- container.flush(); // <3>
-
- final BreadcrumbModelProvider wicketSession = // <4>
- (BreadcrumbModelProvider) AuthenticatedWebSession.get();
- final BreadcrumbModel breadcrumbModel =
- wicketSession.getBreadcrumbModel();
- final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
-
- final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
- breadcrumbs.stream() // <5>
- .filter(entityModel -> entityModel != null)
- .map(EntityModel::getObject) // <6>
- .filter(objectAdapter -> objectAdapter != null)
- .map(ObjectAdapter::getObject) // <7>
- .filter(pojo -> !(pojo instanceof Persistable) ||
- !((Persistable)pojo).dnIsDeleted()) // <8>
- .findFirst();
-
- return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage()); // <9>
- }
- private Object homePage() {
- return homePageProviderService.homePage();
- }
- @Inject
- HomePageProviderService homePageProviderService;
- @Inject
- DomainObjectContainer container;
-}
-----
-<1> override the default imlpementation
-<2> if a non-null object was returned, then return this
-<3> ensure that any persisted objects have been deleted.
-<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
-<5> loop over all breadcrumbs
-<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
-representation (`ObjectAdapter`)
-<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
-<8> if object is persistable (not a view model) then make sure it is not deleted
-<9> return the first object if any, otherwise the home page object (if any).
-
-Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
deleted file mode 100644
index afa113f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_ugfun_faqs_how-to-implement-a-spellchecker]]
-= How to implement a spellchecker?
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
-
-* _What is the easiest way to add a spell checker to the text written in a field in
- a domain object, for instance to check English syntax?_
-
-One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
-
-* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
-
-* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-
-if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
-
-You'll need some way to know which fields should be spell checked. Two ways spring to mind:
-
-* either look at the domain event's identifier
-
-* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker
-interface, eg a `SpellCheckEvent`.
-
-And you'll (obviously) also need some sort of spell checker implementation to call.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
deleted file mode 100644
index baa035a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ugfun_faqs_i18n-label-in-wicket-viewer]]
-= How i18n the Wicket viewer?
-: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/
-
-
-
-From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
-
-* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`. Referencing those via their message id inside a .po file didn't work either. Can this be done?_
-
-
-The above FAQ was raised against `1.10.0`. As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as
-supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
-
-Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
-
-In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[ Wicket's internationalization support], namely resource bundles. This is still supported (as a fallback):
-
-* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
-* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc
deleted file mode 100644
index f08e7df..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_per-user-themes.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-[[_ugfun_faqs_per-user-themes]]
-= Per-user Themes
-: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/
-
-From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
-
-* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors? Would this also be possible for the login page, possibly depending on the used host name?_
-
-
-Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
-
-The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
-
-[source,java]
-.IActiveThemeProvider implementation
-----
-public class UserSettingsThemeProvider implements ActiveThemeProvider {
- ...
- @Override
- public ITheme getActiveTheme() {
- if(IsisContext.getSpecificationLoader().isInitialized()) {
- final String themeName = IsisContext.doInSession(new Callable<String>() {
- @Override
- public String call() throws Exception {
- final Class<UserSettingsService> serviceClass = UserSettingsService.class;
- final UserSettingsService userSettingsService = lookupService(serviceClass);
- final UserSetting activeTheme = userSettingsService.find(
- IsisContext.getAuthenticationSession().getUserName(), ACTIVE_THEME);
- return activeTheme != null ? activeTheme.valueAsString() : null;
- }
- });
- return themeFor(themeName);
- }
- return new SessionThemeProvider().getActiveTheme();
- }
- @Override
- public void setActiveTheme(final String themeName) {
- IsisContext.doInSession(new Runnable() {
- @Override
- public void run() {
- final String currentUsrName = IsisContext.getAuthenticationSession().getUserName();
- final UserSettingsServiceRW userSettingsService =
- lookupService(UserSettingsServiceRW.class);
- final UserSettingJdo activeTheme =
- (UserSettingJdo) userSettingsService.find(currentUsrName, ACTIVE_THEME);
- if(activeTheme != null) {
- activeTheme.updateAsString(themeName);
- } else {
- userSettingsService.newString(
- currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
- }
- }
- });
- }
- private ITheme themeFor(final String themeName) {
- final ThemeProvider themeProvider = settings.getThemeProvider();
- if(themeName != null) {
- for (final ITheme theme : themeProvider.available()) {
- if (themeName.equals(theme.name()))
- return theme;
- }
- }
- return themeProvider.defaultTheme();
- }
- ...
-}
-----
-
-and
-
-[source,java]
-.Using the ActiveThemeProvider
-----
-@Override
-protected void init() {
- super.init();
-
- final IBootstrapSettings settings = Bootstrap.getSettings();
- settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
-
- settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc
deleted file mode 100644
index f71ab81..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_restful-image-property.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugfun_faqs_restful-image-property]]
-= How parse images in RO viewer?
-: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/
-
-
-From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
-
-* _I am trying to display an image in a JavaScript client app, the image comes from
- an Isis RO web service as a string, but it won't show. Is there something I should do to change the message?_
-
-The RO viewer returns the image as a string, in the form:
-
- "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/ ...."
-
-This is in the form:
-
- (filename):(mime type):(binary data in base64)
-
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
-
-To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
deleted file mode 100644
index c2e7340..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_ugfun_faqs_subtype-entity-not-fully-populated]]
-= Subtype not fully populated
-: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/
-
-
-Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
-
-
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties
-as `null`), then check that your actions are not accessing the fields directly. Use getters instead. that is:
-
-[WARNING]
-====
-Properties of domain entities should always be accessed using getters. The only code that should access to fields
-should be the getters themselves.
-====
-
-Why so? Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the
-field is being requested. This is the purpose of the enhancement phase: the bytecode of the original getter method is
-actually wrapped in code that does the lazy loading checking. But hitting the field directly means that the lazy
-loading code does not run.
-
-This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work. But that will be
-because the field has been populated already, for whatever reason.
-
-One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance
-strategy of `NEW_TABLE`, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SupertypeEntity {
- ...
-}
-----
-
-and then:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SubtypeEntity extends SupertypeEntity {
- ...
-}
-----
-
-This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key
-(also primary key) of the subtype table (sometimes called "table per type" strategy). This means that DataNucleus
-might retrieve data from only the supertype table, and the lazily load the subtype fields only as required. This is
-preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
-
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE`
-strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data
-for any given instance from a single table.
-
-Final note: references to other objects (either scalar references or in collections) in particular require that getters
-rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and
-will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
-
-In summary, there's just one rule: *always use the getters, never the fields*.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
deleted file mode 100644
index 9a0a0f7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ugfun_getting-started]]
-= Getting Started
-: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/
-
-
-
-
-To get you up and running quickly, Apache Isis provides a xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps. This is deliberately very minimal so that you won't have to spend lots of time removing generated artifacts. On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app. We strongly recommend that you preserve this structure as you develop your own Isis application.
-
-In this chapter we also discuss the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer]. link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
-
-[NOTE]
-====
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage. Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
-====
-
-
-
-
-== Prerequisites
-
-Apache Isis is a Java based framework, so in terms of prerequisites, you'll need to install:
-
-* Java 7 or 8 JDK
-* link:http://maven.apache.org[Apache Maven] 3.0.5 or later
-
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs. If you're a NetBeans user you should have no problems as it too has strong support for Maven.
-
-When building and running within an IDE, you'll also need to configure the Datanucleus enhancer. This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
-
-For Eclipse the maven integration story is a little less refined. All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
-
-include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
-include::_ugfun_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
deleted file mode 100644
index 9b6a2d9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_datanucleus-enhancer.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ugfun_getting-started_datanucleus-enhancer]]
-= Datanucleus Enhancer
-: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/
-
-
-
-link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as link:http://neo4j.com/[Neo4J], link:http://www.mongodb.org/[MongoDB] and link:http://cassandra.apache.org/[Apache Cassandra].
-
-With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.
-
-[NOTE]
-====
-Bytecode enhancement is actually a requirement of the JDO spec; the process is described in outline http://db.apache.org/jdo/enhancement.html[here].
-====
-
-What this means is that the enhancer -- available as both a Maven plugin and as an Eclipse plugin -- must, one way or another, be integrated into your development environment.
-
-If working from the Maven command line, JDO enhancement is done using the `maven-datanucleus-plugin`. As of 1.9.0, we put all the configuration into an (always active) profile:
-
-[TIP]
-====
-The configuration described below is automatically set up by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-====
-
-
-[source,xml]
-----
-<profile>
- <id>enhance</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <properties>
- <datanucleus-maven-plugin.version>4.0.1</datanucleus-maven-plugin.version>
- </properties>
- <build>
- <plugins>
- <plugin>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-maven-plugin</artifactId>
- <version>${datanucleus-maven-plugin.version}</version>
- <configuration>
- <fork>false</fork>
- <log4jConfiguration>${basedir}/log4j.properties</log4jConfiguration>
- <verbose>true</verbose>
- <props>${basedir}/datanucleus.properties</props>
- </configuration>
- <executions>
- <execution>
- <phase>process-classes</phase>
- <goals>
- <goal>enhance</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
- <dependencies>
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-core</artifactId>
- </dependency>
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-jodatime</artifactId>
- </dependency>
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-api-jdo</artifactId>
- </dependency>
- </dependencies>
-</profile>
-----
-
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] sets up the plugin correctly in the `dom` (domain object model) module. (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
-
-
-
-
-== `META-INF/persistence.xml`
-
-It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persistence.xml` file:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" ?>
-<persistence xmlns="http://java.sun.com/xml/ns/persistence"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
-
- <persistence-unit name="simple"> <!--1-->
- </persistence-unit>
-</persistence>
-----
-<1> change as required; typically is the name of the app.
-
-Again, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
-
-[WARNING]
-====
-If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit]. In this case the `persistence.xml` file is mandatory rather than optional.
-
-This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven. More information can be found xref:dg.adoc#_dg_ide_eclipse[here].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
deleted file mode 100644
index c1924e3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_getting-started_simpleapp-archetype.adoc
+++ /dev/null
@@ -1,278 +0,0 @@
-[[_ugfun_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 `SimpleObjects` domain service which acts as a repository for `SimpleObject` entity. From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
-
-Finally, the domain service also includes a `HomePageViewModel` which acts as a home page for the app.
-
-
-
-== 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.14.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.15.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.
-
-
-=== Using mvn Jetty plugin
-
-First, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
-
-[source,bash]
-----
-mvn -pl webapp jetty:run
-----
-
-
-You can also provide a system property to change the port:
-
-[source,bash]
-----
-mvn -pl webapp 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:dg.adoc#_dg_ide[Developers' 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:ugfun.adoc#_ugfun_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 you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag. The archetype provides the `domainapp.fixture.scenarios.RecreateSimpleObjects` fixture script, for example:
-
-image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
-
-Alternatively, you can run with a different xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] using the `--appManifest` (or `-m`) flag. The archetype provides
-`domainapp.app.DomainAppAppManifestWithFixtures` which specifies the aforementioned `RecreateSimpleObjects` fixture.
-
-
-
-== Using the App
-
-[NOTE]
-====
-These screenshots are for v1.10.0.
-====
-
-
-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 IntelliJ IDEA or Eclipse, do also install the xref:dg.adoc#__dg_ide_intellij_live-templates[live templates (for IntelliJ)] / xref:dg.adoc#__dg_ide_eclipse_editor-templates[editor templates (for Eclipse)]; 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/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc
deleted file mode 100644
index dfcb5ce..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ugfun_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::_ugfun_how-tos_class-structure.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints.adoc[leveloffset=+1]
-include::_ugfun_how-tos_domain-services.adoc[leveloffset=+1]
-include::_ugfun_how-tos_crud.adoc[leveloffset=+1]
-include::_ugfun_how-tos_business-rules.adoc[leveloffset=+1]
-include::_ugfun_how-tos_derived-members.adoc[leveloffset=+1]
-include::_ugfun_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
-include::_ugfun_how-tos_bulk-actions.adoc[leveloffset=+1]
-include::_ugfun_how-tos_simulating-collections-of-values.adoc[leveloffset=+1]
-include::_ugfun_how-tos_render-all-properties-in-tables.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc
deleted file mode 100644
index fba2501..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ugfun_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/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc
deleted file mode 100644
index cf4411e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_business-rules.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ugfun_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/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc
deleted file mode 100644
index 89bda18..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugfun_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_view-models[view model]s and services.
-The class methods 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::_ugfun_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_properties.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_collections.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_actions.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
-
-include::_ugfun_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
deleted file mode 100644
index 20d85b2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_actions.adoc
+++ /dev/null
@@ -1,264 +0,0 @@
-[[_ugfun_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/
-
-
-
-While xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties] and xref:ugfun.adoc#_ugfun_how-tos_class-structure_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
-
-An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
-Such applications are often called CRUD applications (create/read/update/delete).
-
-In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
-So instead actions allow those business rules to be encoded programmatically.
-An Apache Isis application doesn't try to constrain the end-user as to way in which they interact with the user (it doesn't attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren't allowed to go into an invalid state.
-
-For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
-But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
-Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
-If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
-But if the state change is more complex, then most likely an action should be used instead.
-
-
-[[__ugfun_how-tos_class-structure_actions_defining-actions]]
-== Defining actions
-
-Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
-This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:ugfun.adoc#_ugfun_how-tos_business-rules[business rules]); these also not treated as actions.
-And, any method that are annotated with `@Programmatic` will also be excluded.
-But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
-
-For example:
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT) // <1>
-public ShoppingBasket addToBasket(
- Product product,
- @ParameterLayout(named="Quantity") // <2>
- int quantity
- ) {
- ...
- return this;
-}
-----
-<1> `@Action` annotation is optional but used to specify additional domain semantics (such as being idempotent).
-<2> The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
-For the `product` parameter this is reasonable, but not so for the `quantity` parameter (which would by default show up with a name of "int".
-The `@ParameterLayout` annotation provides a UI hint to the framework.
-
-[TIP]
-====
-The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8[paraname8] metamodel extension allows the parameter name to be used in the UI, rather than the type.
-====
-
-
-[[__ugfun_how-tos_class-structure_actions_reference-parameter-types]]
-== (Reference) Parameter types
-
-Parameter types can be value types or reference types.
-In the case of primitive types, the end-user can just enter the value directly through the parameter field.
-In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
-This is done using either a supporting xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
-The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
-
-For example, the `addToBasket(...)` action shown above might well have a :
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)
-public ShoppingBasket addToBasket(
- Product product,
- @ParameterLayout(named="Quantity")
- int quantity
- ) {
- ...
- return this;
-}
-public List<Product> autoComplete0AddToBasket( // <1>
- @MinLength(3) // <2>
- String searchTerm) {
- return productRepository.find(searchTerm); // <3>
-}
-@javax.inject.Inject
-ProductRepository productRepository;
-----
-<1> Supporting `autoComplete` method.
-The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
-It is also required to return a Collection of that type.
-<2> The xref:rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
-<3> The implementation delegates to an injected repository service. This is typical.
-
-Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
-
-[[__ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate]]
-=== Removing boilerplate
-
-To save having to define an `autoCompleteNXxx(...)` method everywhere that a reference to a particular type (such as `Product`) appears as an action parameter, it is also possible to use the `@DomainObject` annotation on `Product` itself:
-
-[source,java]
-----
-@DomainObject(
- autoCompleteRepository=ProductRepository.class // <1>
- autoCompleteAction="find" // <2>
-)
-public class Product ... {
- ...
-}
-----
-<1> Whenever an action parameter requiring a `Product` is defined, provide an autoComplete drop-down automatically
-<2> Use the "find" method of `ProductRepository` (rather than the default name of "autoComplete")
-
-(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the `choicesNXxx()` supporting method can be used.
-This too can be avoided by annotating the referenced class.
-
-For example, suppose we have an action to specify the `PaymentMethodType`, where there are only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
-We could define this as:
-
-[source,java]
-----
-public Order payUsing(PaymentMethodType type) {
- ...
-}
-----
-
-where `PaymentMethodType` would be annotated using:
-
-[source,java]
-----
-@DomainObject(
- bounded=true // <1>
-)
-public class PaymentMethodType ... {
- ...
-}
-----
-<1> only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.
-
-
-[[__ugfun_how-tos_class-structure_actions_collection-parameter-types]]
-== Collection Parameter types
-
-Action parameters can also be collections of values (for example `List<String>`), or can be collections of references (such as `List<Customer>`).
-
-For example:
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)
-public ShoppingBasket addToBasket(
- List<Product> products,
- @ParameterLayout(named="Quantity") int quantity
- ) {
- ...
- return this;
-}
-public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
- return ...
-}
-----
-
-As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:ugfun.adoc#__ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate[above]).
-
-
-[[__ugfun_how-tos_class-structure_actions_optional-parameters]]
-== Optional Parameters
-
-Whereas the xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_optional-properties[optionality of properties] is defined using xref:rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
-Instead, either the xref:rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true") // <1>
-@lombok.Getter @lombok.Setter
-private LocalDate shipBy;
-
-public Order invoice(
- PaymentMethodType paymentMethodType,
- @Nullable // <2>
- @ParameterLayout(named="Ship no later than")
- LocalDate shipBy) {
- ...
- setShipBy(shipBy)
- return this;
-}
-----
-<1> Specifies the property is optional.
-<2> Specifies the corresponding parameter is optional.
-
-See also xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
-
-[[__ugfun_how-tos_class-structure_actions_string-parameters]]
-== ``String`` Parameters (Length)
-
-Whereas the xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-strings[length of string properties] is defined using xref:rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50) // <1>
-@lombok.Getter @lombok.Setter
-private String firstName;
-
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String lastName;
-
-public Customer updateName(
- @Parameter(maxLength=50) // <2>
- @ParameterLayout(named="First name")
- String firstName,
- @Parameter(maxLength=50)
- @ParameterLayout(named="Last name")
- String lastName) {
- setFirstName(firstName);
- setLastName(lastName);
- return this;
-}
-----
-<1> Specifies the property length using the JDO xref:rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
-<2> Specifies the parameter length using the (Apache Isis) xref:rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
-
-[IMPORTANT]
-====
-Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply set the instance field directly.
-This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
-====
-
-See also xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
-
-[[__ugfun_how-tos_class-structure_actions_bigdecimal-parameters]]
-== ``BigDecimal``s (Precision)
-
-Whereas the xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-bigdecimals[precision of BigDecimal properties] is defined using xref:rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2) // <1>
-@lombok.Getter @lombok.Setter
-private BigDecimal discountRate;
-
-public Order updateDiscount(
- @javax.validation.constraints.Digits(fraction=2) // <2>
- @ParameterLayout(named="Discount rate")
- String discountRate) {
- setDiscountRate(discountRate);
- return this;
-}
-----
-<1> Specifies the property precision using xref:rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
-<2> Specifies the corresponding parameter precision using xref:rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
-
-See also xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index 6bdc20b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_class-definition.adoc
+++ /dev/null
@@ -1,201 +0,0 @@
-[[_ugfun_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/
-
-
-
-Apache Isis supports recognises three main types of domain classes:
-
-* domain entities - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
-
-* domain services - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
-
-* view models - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
-
-Domain classes are generally recognized using annotations.
-Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required).
-JAXB can also be used for view models.
-Apache Isis recognizes some of the JDO and JAXB annotations and infers domain semantics from these annotations.
-
-You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
-The framework also defines supplementary annotations, `@DomainObjectLayout` and `@DomainServiceLayout`.
-These provide hints relating to the layout of the domain object in the user interface.
-(Alternatively, these UI hints can be defined in a supplementary xref:ugfun.adoc#_ugfun_object-layout[`.layout.xml`] file.
-
-We use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
-By convention there will be a single top-level package corresponding to the module.
-
-For example, the (non-ASF) link:https://github.com/incodehq/incode-module-document[Document module] (part of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package of `org.incode.module.document`.
-Within the module there may be various subpackages, but its the module defines the namespace.
-
-In the same way that the Java module act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
-
-
-[[__ugfun_how-tos_class-structure_class-definition_entities]]
-== Entities
-
-Entities are persistent domain objects.
-Their persistence is handled by JDO/DataNucleus, which means that it will generally be decorated with both DataNucleus and Apache Isis annotations.
-The following is typical:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( // <1>
- identityType=IdentityType.DATASTORE, // <2>
- schema = "simple", // <3>
- table = "SimpleObject"
-)
-@javax.jdo.annotations.DatastoreIdentity( // <4>
- strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
- column="id"
-)
-@javax.jdo.annotations.Version( // <5>
- strategy= VersionStrategy.DATE_TIME,
- column="version"
-)
-@javax.jdo.annotations.Queries({
- @javax.jdo.annotations.Query( // <6>
- name = "findByName",
- value = "SELECT "
- + "FROM domainapp.modules.simple.dom.impl.SimpleObject "
- + "WHERE name.indexOf(:name) >= 0 ")
-})
-@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <7>
-@DomainObject( // <8>
- objectType = "simple.SimpleObject"
-)
-public class SimpleObject
- implements Comparable<SimpleObject> { // <9>
-
- public SimpleObject(final String name) { // <10>
- setName(name);
- }
-
- ...
-
- @Override
- public String toString() {
- return ObjectContracts.toString(this, "name"); // <11>
- }
- @Override
- public int compareTo(final SimpleObject other) {
- return ObjectContracts.compare(this, other, "name"); // <9>
- }
-}
-----
-<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
-The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
-Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
-<2> Indicates how identifiers for the entity are handled.
-Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
-<3> Specifies the RDBMS database schema and table name for this entity will reside.
-The schema should correspond with the module in which the entity resides.
-The table will default to the entity name if omitted.
-<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
-A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
-<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
-<6> The `@Query` annotation (usually several of them, nested within a `@Queries` annotation) defines queries using JDOQL.
-DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
-<7> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
-In the example above, the "name" property is assumed to be unique.
-<8> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
-It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
-In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
-<9> Although not required, we strongly recommend that all entities are naturally `Comparable`.
-This then allows parent/child relationships to be defined using ``SortedSet``s; RDBMS after all are set-oriented.
-The `ObjectContracts` utility class provided by Apache Isis makes it easy to implement the `compareTo()` method, but you can also just use an IDE to generate an implementation or roll your own.
-<10> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
-In regular Java programming we would represent this using a constructor that defines these mandatory properties, and in Apache Isis/DataNucleus we can likewise define such a constructor.
-When DataNucleus rehydrates domain entities from the database at runtime, it actually requires a no-arg constructor (it then sets all state reflectively).
-However, there is no need to provide such a no-arg constructor; it is added by the enhancer process.
-<11> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
-
-
-[[__ugfun_how-tos_class-structure_class-definition_domain-services]]
-== Domain Services
-
-Domain services are generally singletons that are automatically injected into other domain services.
-A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
-But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
-
-The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:rgsvc.adoc#[Domain Services Reference Guide].
-Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
-
-The following is a typical menu service:
-
-[source,java]
-----
-@DomainService( // <1>
- nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout( // <2>
- named = "Simple Objects",
- menuOrder = "10"
-)
-public class SimpleObjectMenu {
-
- ...
-
- @Action(semantics = SemanticsOf.SAFE)
- @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
- @MemberOrder(sequence = "2")
- public List<SimpleObject> findByName( // <3>
- @ParameterLayout(named="Name")
- final String name
- ) {
- return simpleObjectRepository.findByName(name);
- }
-
- @javax.inject.Inject
- SimpleObjectRepository simpleObjectRepository; // <4>
-}
-----
-<1> The (Apache Isis) `@DomainService` annotation is used to identify the class as a domain service.
-Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
-The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
-<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
-In the example above the menu is named "Simple Objects" (otherwise it would have defaulted to "Simple Object Menu", based on the class name, while the `menuOrder` attribute determines the order of the menu with respect to other menu services.
-<3> The `findByName` method is annotated with various Apache Isis annotations (`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
-The implementation delegates to an `SimpleObjectRepository` service, which is injected.
-<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
-The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[below].
-
-
-[[__ugfun_how-tos_class-structure_class-definition_view-models]]
-== View Models
-
-xref:ugbtb.adoc#_ugbtb_view-models[View model]s are similar to entities in that (unlike domain services) there can be many instances of any given type; but they differ from entities in that they are not persisted into a database.
-Instead they are recreated dynamically by serializing their state, ultimately into the URL itself.
-
-A common use case for view models is to support a business process.
-For example, in an invoicing application there could be an `InvoiceRun` view model, which lists all the invoices due to be paid (each month, say) and provides actions to allow those invoices to be processed.
-
-Another use case is for a view model to act as a proxy for an entity that is managed in an external system.
-For example, a `Content` view model could represent a PDF that has been scanned and is held within a separate Content Management system.
-
-A third use case is to define DTOs that act as a stable projection of one or more underlying entities.
-Apache Isis' xref:ugvro.adoc[Restful Objects] viewer provides a REST API that then allows REST clients to query the application using these DTOs; useful for integration scenarios.
-
-Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
-For example:
-
-[source,java]
-----
-@XmlRootElement(name = "invoiceRun") // <1>
-@XmlType(
- propOrder = { // <2>
- ...
- }
-)
-public class InvoiceRun {
- ...
-}
-----
-<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
-<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
-
-Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
-Properties can be ignored (for serialization) using `@XmlTransient`.