http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index 70b3659..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_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:../ugvw/ugvw.adoc#_ugvw_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/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/ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[below].
-
-
-[[__ugfun_how-tos_class-structure_class-definition_view-models]]
-== View Models
-
-xref:../ugbtb/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/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`.

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
deleted file mode 100644
index 16a58de..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_ugfun_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/
-
-
-A collection is an instance variable of a domain object, of a collection type 
that holds references to other domain objects.
-For example, a `Customer` may have a collection of ``Order``s).
-
-It's ok for a 
xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain
 entity] to reference another domain entity, and for a 
xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view
 model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to 
view model (DataNucleus will not know how to persist that view model).
-
-Formally speaking, a collection is simply a regular JavaBean getter, returning 
a collection type (subtype of `java.util.Collection`).
-Most collections (those that are modifiable) will also have a setter and (if 
persisted) a backing instance field.
-And collections properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Collection` annotation for capturing 
domain semantics.
-It also provides a `@CollectionLayout` for UI hints (though the information in 
this annotation may instead be provided by a supplementary 
xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the collections of domain entities are often annotated with various 
JDO/DataNucleus annotations, most notable `javax.jdo.annotations.Persistent`.
-This and other annotations can be used to specify if the association is 
bidirectional, and whether to define a link table or not to hold foreign key 
columns.
-
-* for the collections of view models, then JAXB annotations such as 
`@javax.xml.bind.annotation.XmlElementWrapper` and 
`@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB 
and infers some domain semantics from them (for example, the maximum allowable 
length of a string property).
-
-Unlike 
xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], 
the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not 
allow collections to be "edited".
-Instead, 
xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_actions[action]s can be 
written that will modify the contents of the collection as a side-effect.
-For example, a `placeOrder(...)` action will likely add an `Order` to the 
`Customer#orders` collection.
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's 
common to use link:https://projectlombok.org/[Project Lombok] to code generate 
these methods at compile time (using Java's annotation processor) simply by 
adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-
-
-== Mapping bidir 1:m
-
-Bidirectional one-to-many collections are one of the most common types of 
associations between two entities.
-In the parent object, the collection can be defined as:
-
-[source,java]
-----
-public class ParentObject
-        implements Comparable<ParentObject>{
-
-    @javax.jdo.annotations.Persistent(
-        mappedBy = "parent",                                                // 
<1>
-        dependentElement = "false"                                          // 
<2>
-    )
-    @Collection                                                             // 
<3>
-    @lombok.Getter @lombok.Setter
-    private SortedSet<ChildObject> children = new TreeSet<ChildObject>();   // 
<4>
-
-}
-----
-<1> indicates a bidirectional association; the foreign key pointing back to 
the `Parent` will be in the table for `ChildObject`
-<2> disable cascade delete
-<3> (not actually required in this case, because no attributes are set, but 
acts as a useful reminder that this collection will be rendered in the UI by 
Apache Isis)
-<4> uses a `SortedSet` (as opposed to some other collection type; discussion 
below)
-
-while in the child object you will have:
-
-[source,java]
-----
-public class ChildObject
-        implements Comparable<ChildObject> {    // <1>
-
-    @javax.jdo.annotations.Column(
-        allowsNull = "false"                    // <2>
-    )
-    @Property(editing = Editing.DISABLED)       // <3>
-    @lombok.Getter @lombok.Setter
-    private ParentObject parent;
-}
-----
-<1> implements `Comparable` because is mapped using a `SortedSet`
-<2> mandatory; every child must reference its parent
-<3> cannot be edited directly
-
-Generally speaking you should use `SortedSet` for collection types (as opposed 
to `Set`, `List` or `Collection`).
-JDO/Datanucleus does support the mapping of these other types, but RDBMS are 
set-oriented, so using this type introduces the least friction.
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus 
documentation for 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many]
 associations, 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one]
 associations, 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many]
 associations, and so on.
-
-Also, while JDO/DataNucleus itself supports `java.util.Map` as a collection 
type, this is not supported by Apache Isis.
-If you do wish to use this collection type, then annotate the getter with 
`@Programmatic` so that it is ignored by the Apache Isis framework.
-====
-
-
-
-== Value vs Reference Types
-
-Apache Isis can (currently) only provide a UI for collections of references.
-While you can use DataNucleus to persist collections/arrays of value types, 
such properties must be annotated as `@Programmatic` so that they are ignored 
by Apache Isis.
-
-If you want to visualize an array of value types in Apache Isis, then one 
option is to wrap value in a view model, as explained 
xref:../ugfun/ugfun.adoc#_ugfun_how-tos_simulating-collections-of-values[elsewhere].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
deleted file mode 100644
index 26c5682..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
+++ /dev/null
@@ -1,103 +0,0 @@
-[[_ugfun_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 framework defines many additional services (such as 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); 
these are injected in exactly the same manner.
-
-Sometimes there may be multiple services that implement a single type.
-This is common for example for SPI service, whereby one module defines an SPI 
service, and other module(s) in the application implement that service.
-To support this, the framework also allows lists of services to be injected.
-
-When there are multiple service implementations of a given type, the framework 
will inject the service with highest priority, as defined through 
xref:../rgant/rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`]
 (even for domain services that are not menus), lowest first.
-If a list of services is injected, then that list will be ordered according to 
`menuOrder`, again lowest first.
-
-
-
-[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;
-}
-----
-
-To inject a list of services, use:
-
-[source,java]
-----
-public class DocumentService {
-    ...
-    @javax.inject.Inject
-    List<PaperclipFactory> paperclipFactories;
-}
-----
-
-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
-
-The framework 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;
-    }
-    ...
-}
-----
-
-Lists of services can be injected in a similar manner.
-
-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/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index c435cb3..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ugfun_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/
-
-
-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.
-
-Since JDO/DataNucleus handles persistence, its annotations are requiredto 
specify semantics such as optionality or maximum length on properties.
-However, 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
-|(JDO) property
-|action parameter
-
-|string (length)
-|`@javax.jdo.annotations.Column(length=50)`
-|`@javax.jdo.annotations.Parameter(maxLength=50)`
-
-|big decimal (precision)
-|`@javax.jdo.annotations.Column(scale=2)`
-|`@javax.validation.constraints.Digits(fraction=2)`
-
-|optionality
-|`@Column(allowsNull="true")`
-|`@Nullable` or `ParameterLayout(optionality=Optionality.OPTIONAL`) (also 
`@Optional`, now deprecated)
-|===
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
deleted file mode 100644
index 5a49a5b..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
+++ /dev/null
@@ -1,397 +0,0 @@
-[[_ugfun_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/
-
-
-A property is an instance variable of a domain object, of a scalar type, that 
holds some state about either a 
xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain
 entity] or a 
xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view
 model].
-
-For example, a ``Customer``'s `firstName` would be a property, as would their 
`accountCreationDate` that they created their account.
-All properties have at least a "getter" method, and most properties have also 
a "setter" method (meaning that they are mutable).
-Properties that do _not_ have a setter method are derived properties, and so 
are not persisted.
-
-Formally speaking, a property is simply a regular JavaBean getter, returning a 
scalar value recognized by the framework.
-Most properties (those that are editable/modifiable) will also have a setter 
and (if persisted) a backing instance field.
-And most properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Property` annotation for capturing 
domain semantics.
-It also provides a `@PropertyLayout` for UI hints (though the information in 
this annotation may instead be provided by a supplementary 
xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the properties of domain entities are often annotated with the 
JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
-For property references, there may be other annotations to indicate whether 
the reference is bidirectional.
-It's also possible (using annotations) to define a link table to hold foreign 
key columns.
-
-* for the properties of view models, then JAXB annotations such as 
`@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB 
and infers some domain semantics from them (for example, the maximum allowable 
length of a string property).
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's 
common to use link:https://projectlombok.org/[Project Lombok] to code generate 
these methods at compile time (using Java's annotation processor) simply by 
adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-The 
xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp 
archetype] uses this approach.
-
-
-[[__ugfun_how-tos_class-structure_properties_value-vs-reference-types]]
-== Value vs Reference Types
-
-Properties can be either a value type (strings, int, date and so on) or be a 
reference to another object (for example, an `Order` referencing the `Customer` 
that placed it).
-
-For example, to map a string value type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter       // <1>
-private String notes;
-----
-<1> using link:https://projectlombok.org/[Project Lombok] annotations to 
reduce boilerplate
-
-You could also add the `@Property` annotation if you wished:
-
-[source,java]
-----
-@Property
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-Although in this case it is not required (none of its attributes have been 
set).
-
-Or to map a reference type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private Customer customer;
-----
-
-It's ok for a 
xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain
 entity] to reference another domain entity, and for a 
xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view
 model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to 
view model (DataNucleus will not know how to persist that view model).
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus 
documentation for 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many]
 associations, 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one]
 associations, 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many]
 associations, and so on.
-====
-
-For domain entities, 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:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties
 vs Parameters] section provides a handy reference of each.
-
-
-[[__ugfun_how-tos_class-structure_properties_optional-properties]]
-== Optional Properties
-
-(For domain entities) 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=...)`, or (because it's much less verbose) 
using `@javax.annotation.Nullable`.
-
-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, you can write:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-rather than the more verbose:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@Property(optionality=Optionality.OPTIONAL)
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-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).
-
-[[__ugfun_how-tos_class-structure_properties_editable-properties]]
-== Editable Properties
-
-Apache Isis provides the capability to allow individual properties to be 
modified.
-This is specified using the `@Property(editing=...)` attribute.
-
-For example:
-
-[source,java]
-----
-@Property(editing = Editing.ENABLED)
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-If this is omitted then whether editing is enabled or disabled is defined 
globally, in the `isis.properties` configuration file; see 
xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference
 configuration guide] for further details.
-
-
-[[__ugfun_how-tos_class-structure_properties_ignoring-properties]]
-== Ignoring Properties
-
-By default Apache Isis will automatically render all properties in the 
xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
-To get Apache Isis to ignore a property (exclude it from its metamodel), 
annotate the getter using `@Programmatic`.
-
-Similarly, you can tell JDO/DataNucleus to ignore a property using the 
`@javax.jdo.annotations.NotPersistent` annotation.
-This is independent of Apache Isis; in other words that property will still be 
rendered in the UI (unless also annotated with `@Programmatic`).
-
-For view models, you can tell JAXB to ignore a property using the 
`@javax.xml.bind.annotation.XmlTransient` annotation.
-Again, this is independent of Apache Isis.
-
-
-[[__ugfun_how-tos_class-structure_properties_derived-properties]]
-== Derived Properties
-
-Derived properties are those with a getter but no setter.
-Provided that the property has not been annotated with `@Programmatic`, these 
will still be rendered in the UI, but they will be read-only (not editable) and 
their state will not be persisted.
-
-Subtly different, it is also possible to have non-persisted but still editable 
properties.
-In this case you will need a getter and a setter, but with the getter 
annotated using `@NotPersistent`.
-The implementation of these getters and setters will most likely persist state 
using other properties (which might be hidden from view using `@Programmatic`).
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.NotPersistent
-@Property(editing=Editing.ENABLED)
-public String getAddress() { return addressService.toAddress( getLatLong() ); 
}             // <1>
-public void setAddress(String address) { 
setLatLong(addressService.toLatLong(address)); }
-
-@javax.jdo.annotations.Column
-private String latLong;
-@Programmatic
-public String getLatLong() { return latLong; }                                 
             // <2>
-public void setLatLong(String latLong) { this.latLong = latLong; }
-
-@javax.inject.Inject
-AddressService addressService;                                                 
             // <3>
-----
-<1> the representation of the address, in human readable form, eg "10 Downing 
Street, London, UK"
-<2> the lat/long representation of the address, eg "51.503363;-0.127625"
-<3> an injected service that can convert to/from address and latLong.
-
-[[__ugfun_how-tos_class-structure_properties_mapping-strings]]
-== Mapping ``String``s (Length)
-
-By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
-To limit the length, use the `@Column(length=...)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String firstName
-----
-
-This is a good example of a case where Apache Isis infers domain semantics 
from the JDO annotation.
-
-
-
-[[__ugfun_how-tos_class-structure_properties_mapping-joda-dates]]
-== Mapping JODA Date
-
-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 link: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:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="true")
-@javax.jdo.annotations.Column(allowsNull="true")
-@Getter @Setter
-private LocalDate dueBy;
-----
-
-[[__ugfun_how-tos_class-structure_properties_mapping-bigdecimals]]
-== Mapping ``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]
-----
-@lombok.Getter @lombok.Setter
-private BigDecimal 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)
-@lombok.Getter @lombok.Setter
-private BigDecimal 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].
-
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs]]
-== Mapping ``Blob``s and ``Clob``s
-
-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:../ugfun/ugfun.adoc#__ugfun_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.
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-blobs]]
-=== Mapping ``Blob``s
-
-For example, in the `ToDoItem` class (of the 
https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442[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")
-})
-@Property(
-        optionality = Optionality.OPTIONAL
-)
-@lombok.Getter @lombok.Setter
-private Blob 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")
-})
-@Property(
-    optionality = Optionality.MANDATORY
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".
-There can be differences in behaviour between JDBC drivers.
-====
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-clobs]]
-=== Mapping ``Clob``s
-
-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.
-====
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-to-varbinary-or-varchar]]
-=== 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.
-
-
-
-[[__ugfun_how-tos_class-structure_properties_handling-mandatory-properties-in-subtypes]]
-== 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 there is a table for both superclass and subclass, in 1:1 
correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the 
properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking 
- the property is mandatory in the subtype - but it must be mapped as nullable 
in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache 
Isis we want to enforce it being mandatory. This can be done using the 
`@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
-    @javax.jdo.annotations.Column(allowsNull="true")
-    @Property(optionality=Optionality.MANDATORY)
-    @lombok.Getter @lombok.Setter
-    private LocalDate date;
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but 
still supported `@Optional` annotation and `@Mandatory` annotations.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
deleted file mode 100644
index efa18bc..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_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: FIXME
-
-
-## Instantiating and Persisting Objects
-
-NOTE: FIXME - using ``DomainObjectContainer``'s support for  
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[creation]
 and 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
-
-## Finding Objects
-
-NOTE: FIXME - using 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-
-### Using DataNucleus type-safe queries
-
-NOTE: FIXME - as described 
xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries[here]
-
-
-
-## Deleting Objects
-
-NOTE: FIXME using ``DomainObjectContainer``'s support for  
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
deleted file mode 100644
index abcf5e9..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ugfun_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: FIXME
-
-
-
-
-== Derived Property
-
-NOTE: FIXME
-
-
-
-
-== Derived Collection
-
-NOTE: FIXME
-
-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: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
-
-
-
-== Trigger on collection change
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
deleted file mode 100644
index 4159152..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
+++ /dev/null
@@ -1,312 +0,0 @@
-[[_ugfun_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:../ugfun/ugfun.adoc#_ugfun_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 xref:../rgsvc/rgsvc.adoc[domain services] reference 
guide.
-
-
-
-[[__ugfun_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_CONTRIBUTIONS_ONLY` indicates that the actions should not 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:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More 
information
-about using contributions and mixins to keep your domain application decoupled 
can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and 
xref:../ugbtb/ugbtb.adoc#_ugbtb_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:../ugfun/ugfun.adoc#__ugfun_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/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 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query 
results caching through the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and 
support for co-ordinating bulk actions through the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
 service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide 
for further details.
-
-
-
-
-== Registering domain services
-
-The easiest way to register domain services is using 
xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
 to specify the modules
-which contain 
xref:../rgant/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/rgsvc.adoc[domain services] reference guide 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/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/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
-
-
-
-== The getId() method
-
-Optionally, a service may provide a 
xref:../rgcms/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/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
deleted file mode 100644
index 9db7ccc..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_ugfun_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: FIXME
-
-
-== For Properties
-
-NOTE: FIXME
-
-### Choices for Property
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for property
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for property
-
-NOTE: FIXME -  
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-== For Action Parameters
-
-NOTE: FIXME
-
-### Choices for action parameter
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Dependent choices for action params
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for action param
-
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for action param
-
-NOTE: FIXME -  
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-
-== For both Properties and Action Parameters
-
-NOTE: FIXME
-
-
-### Drop-down for limited number of instances
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
-
-
-### Auto-complete (repository-based)
-
-xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
deleted file mode 100644
index fa370de..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ugfun_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/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
deleted file mode 100644
index 4402b7c..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugfun_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: FIXME
-
-
-
-== Persistence Concerns
-
-NOTE: FIXME -  easiest to simply store using DataNucleus' support for 
collections, marked as 
xref:../rgant/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.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
deleted file mode 100644
index be5a865..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ugfun_how-tos_ui-hints]]
-= UI Hints
-: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 Apache Isis programming model includes several mechanisms for a domain 
object to provide UI hints.  These range from their title (so an end-user can 
distinguish one object from another) through to hints that can impact their CSS 
styling.
-
-include::_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_layout.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui_are-you-sure.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
deleted file mode 100644
index 7c15e16..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ugfun_how-tos_ui-hints_action-icons-and-css]]
-= Action Icons and CSS
-: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 allows link:http://fortawesome.github.io/Font-Awesome/icons/[font 
awesome] icons to be associated with each action, and for 
link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to 
action rendered as buttons.
-
-These UI hint can be applied either to individual actions, or can be applied 
en-masse using pattern matching.
-
-== Per action
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`]
 and 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
-
-
-Alternatively, you can specify these hints dynamically in the 
xref:../ugvw/ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
-
-
-== Per pattern matching
-
-Rather than annotating every action with 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 and 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`]
 you can instead specify the UI hint globally using regular expressions.
-
-The xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] 
`isis.reflector.facet.cssClassFa.patterns` is a comma separated list of 
key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClassFa.patterns=\
-                        new.*:fa-plus,\
-                        add.*:fa-plus-square,\
-                        create.*:fa-plus,\
-                        list.*:fa-list, \
-                        all.*:fa-list, \
-                        download.*:fa-download, \
-                        upload.*:fa-upload, \
-                        execute.*:fa-bolt, \
-                        run.*:fa-bolt
-----
-
-where the key is a regex matching action names (eg `create.*`) and the value 
is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon 
name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action 
members matching the regex.
-
-
-Similarly, the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration 
property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of 
key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClass.patterns=\
-                        delete.*:btn-warning
-----
-
-where (again)the key is a regex matching action names (eg `delete.*`) and the 
value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg 
`btn-warning) to be applied (as per `@CssClass()`) to all action members 
matching the regex.
-
-[TIP]
-====
-We strongly recommend that you use this technique rather than annotating each 
action with 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 or 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].
  Not only is the code more maintainable, you'll also find that it forces you 
to be consistent in your action names.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
deleted file mode 100644
index 7ef9e66..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ugfun_how-tos_ui-hints_eager-rendering]]
-= Eager rendering
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-By default, collections all rendered lazily, in other words in a "collapsed" 
table view:
-
-NOTE: FIXME - screenshot here
-
-For the more commonly used collections we want to show the table expanded:
-
-NOTE: FIXME - screenshot here
-
-For this we annotate the collection using the 
`@CollectionLayout(render=RenderType.EAGERLY`; for example
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-@Collection
-@CollectionLayout(
-    render = RenderType.EAGERLY
-)
-public Set<ToDoItem> getDependencies() {
-    return dependencies;
-}
-----
-
-Alternatively, it can be specified the `Xxx.layout.json` file:
-
-[source,javascript]
-----
-"dependencies": {
-    "collectionLayout": {
-        "render": "EAGERLY"
-    },
-}
-----
-
-[WARNING]
-====
-It might be thought that collections that are eagerly rendered should also be 
eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", 
defaultFetchGroup="true")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-...
-----
-
-While this can be done, it's likely to be a bad idea, because doing so will 
cause DataNucleus to query for more data than required even if the object is 
being rendered within some referencing object's table.
-
-Of course, your mileage may vary, so don't think you can't experiment.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
deleted file mode 100644
index a4b02a1..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugfun_how-tos_ui-hints_layout]]
-= Layout
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-See the xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] chapter.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
deleted file mode 100644
index 0b9e432..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ugfun_how-tos_ui-hints_names-and-descriptions]]
-= Names and Descriptions
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-NOTE: FIXME
-
-
-
-NOTE: see also xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[Internationalization]
-
-== Class (object)
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
-
-
-== Property
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
-
-
-
-== Collections
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
-
-
-
-== Actions
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], 
xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
-
-
-== Action Parameters
-
-NOTE: FIXME - 
xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`],
 
xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
-
-
-[TIP]
-====
-If you're running on Java 8, then note that it's possible to write Isis 
applications without using `@ParameterLayout(named=...)` annotation.  Support 
for this can be found in the 
link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' 
paraname8] metamodel extension (non-ASF).  (In the future we'll fold this into 
core).  See also our guidance on 
xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading
 to Java 8].
-====
-
-
-
-

Reply via email to