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 2015/06/16 07:42:19 UTC
[31/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc
new file mode 100644
index 0000000..7a6bb7b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc
@@ -0,0 +1,27 @@
+[[_ug_headless-access]]
+= Headless access
+: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 tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:ug.adoc#_ug_wicket-viewer[Wicket] or xref:ug.adoc#_ug_restfulobjects-viewer[Restful] viewers.
+
+There are several main use-cases:
+
+* enabling background execution, eg of a thread managed by Quartz scheduler and running within the webapp
+
+* integration from other systems, eg for a subscriber on a pub/sub mechanism such as Camel, pushing changes through an Isis domain model.
+
+* leveraging an Isis application within a batch process
+
+Note that the calling thread runs in the same process space as the Isis domain object model (must be physically linked to the JAR files containing the domain classes). For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer] is usually the way to go.
+
+The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Isis metamodel and runtime. Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods. However the <<WrapperFactory>> service could be used to enforce such business rules if required.
+
+
+
+include::_ug_headless-access_AbstractIsisSessionTemplate.adoc[leveloffset=+1]
+include::_ug_headless-access_BackgroundCommandExecution.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc
new file mode 100644
index 0000000..7402a2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc
@@ -0,0 +1,40 @@
+[[_ug_headless-access_AbstractIsisSessionTemplate]]
+= AbstractIsisSessionTemplate
+: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 `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Isis framework, in order to resolve and interact with entities.
+
+The class itself is intended to be subclassed:
+
+[source,java]
+----
+public abstract class AbstractIsisSessionTemplate {
+
+ public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
+ protected abstract void doExecute(Object context); // <2>
+
+ protected ObjectAdapter adapterFor(final Object targetObject) { ... }
+ protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
+
+ protected PersistenceSession getPersistenceSession() { ... }
+ protected IsisTransactionManager getTransactionManager() { ... }
+ protected AdapterManager getAdapterManager() { ... }
+}
+----
+<1> `execute(...)` sets up the `IsisSession` and delegates to ...
+<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
+The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
+
+The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary.
+
+
+[TIP]
+====
+One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc
new file mode 100644
index 0000000..1c82eff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc
@@ -0,0 +1,45 @@
+[[_ug_headless-access_BackgroundCommandExecution]]
+= BackgroundCommandExecution
+: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 `BackgroundCommandExecution` class (a subclass of <<AbstractIsisSessionTemplate>>) is intended to simplify the execution of background ``Command``s persisted by way of the <<CommandService>> and the <<BackgroundCommandService>>.
+
+Its signature is:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
+ protected void doExecute(Object context) { ... }
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
+}
+----
+<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
+
+This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
+
+The diagram below (http://yuml.me/edit/363b335f[yuml.me/363b335f]) shows the dependencies between these various classes:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
+
+
+
+
+
+
+
+== Background Execution
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
+
+This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] and xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below (link:http://yuml.me/edit/25343da1[yuml.me/25343da1]) shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
new file mode 100644
index 0000000..d03210e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
@@ -0,0 +1,20 @@
+[[_ug_how-tos]]
+= How tos
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This chapter provides instructions on how to go about actually developing Isis domain applications.
+
+
+include::_ug_how-tos_class-structure.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints.adoc[leveloffset=+1]
+include::_ug_how-tos_domain-services.adoc[leveloffset=+1]
+include::_ug_how-tos_crud.adoc[leveloffset=+1]
+include::_ug_how-tos_entity-relationships.adoc[leveloffset=+1]
+include::_ug_how-tos_contributed-members.adoc[leveloffset=+1]
+include::_ug_how-tos_business-rules.adoc[leveloffset=+1]
+include::_ug_how-tos_derived-members.adoc[leveloffset=+1]
+include::_ug_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
new file mode 100644
index 0000000..4b0fdd0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
@@ -0,0 +1,72 @@
+[[_ug_how-tos_business-rules]]
+= Business Rules
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+
+== Visibility ("see it")
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`]
+
+### Hide a Property
+
+### Hide a Collection
+
+### Hide an Action
+
+### Hide a Contributed Property, Collection or Action
+
+### All Members Hidden
+
+
+
+
+== Usability ("use it")
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-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")
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] and xref:rg.adoc#_rg_methods_reserved_manpage-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
+
+IMPORTANT: TODO - using xref:rg.adoc#_rg_annotations_manpage-Action_mustSatisfy[`@Action#mustSatisfy()`], xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
new file mode 100644
index 0000000..860a5a3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
@@ -0,0 +1,38 @@
+[[_ug_how-tos_class-structure]]
+= Class Structure
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Apache Isis works by building a metamodel of the domain objects: entities, view models and services. The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions. The class members of domain services is simpler: just behaviour, ie actions.
+
+In the automatically generated UI a property is rendered as a field. This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity. A collection is generally rendered as a table.
+
+In order for 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 Isis programming model.
+
+[TIP]
+====
+In fact, Isis programming model is extensible; you can teach 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 Isis programming model xref:ug.adoc#_ug_extending_programming-model[here].
+====
+
+
+include::_ug_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_properties.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_collections.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_actions.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
+
+include::_ug_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
+
+include::_ug_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
new file mode 100644
index 0000000..d19d7fe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
@@ -0,0 +1,26 @@
+[[_ug_how-tos_class-structure_action-parameters]]
+= Action Parameters
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+IMPORTANT: TODO
+
+
+
+== ``String``s (Length)
+
+IMPORTANT: TODO
+
+
+== ``BigDecimal``s (Precision)
+
+IMPORTANT: TODO
+
+
+== Optional
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
new file mode 100644
index 0000000..fe7fef2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
@@ -0,0 +1,19 @@
+[[_ug_how-tos_class-structure_actions]]
+= Actions
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+IMPORTANT: TODO
+
+
+[NOTE]
+====
+While Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
+
+The workaround is to mark the collection as `@Programmatic`, as described in xref:ug.adoc#_ug_how-tos_class-structure_ignoring-methods[Ignoring Methods]. This ensures that the collection is ignored by Isis.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
new file mode 100644
index 0000000..ed7c1c6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
@@ -0,0 +1,24 @@
+[[_ug_how-tos_class-structure_class-definition]]
+= Class Definition
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+IMPORTANT: WIP
+
+
+Classes are defined both to Isis and (if an entity) also to JDO/DataNucleus.
+
+
+We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then reason about all the classes in that package/namespace as a single unit.
+
+In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+
+[TIP]
+====
+For more on this topic, see the topic discussing modules and xref:ug.adoc#_ug_more-advanced_decoupling[decoupling].
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
new file mode 100644
index 0000000..b23920d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
@@ -0,0 +1,26 @@
+[[_ug_how-tos_class-structure_collections]]
+= Collections
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+IMPORTANT: WIP
+
+
+[NOTE]
+====
+While Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
+
+Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Isis has no default visualization.
+
+One workaround is to mark the collection as xref:rg.adoc#_rg_annotations_manpage-Progammatic[`@Progammatic`]. This ensures that the collection is ignored by Isis.
+
+Another workaround is to wrap each value in a view model, as explained in this xref:ug.adoc#_ug_more-advanced_tips-n-tricks_simulating-collections-of-values[tip].
+====
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
new file mode 100644
index 0000000..523668b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
@@ -0,0 +1,16 @@
+[[_ug_how-tos_class-structure_ignoring-methods]]
+= Ignoring Methods
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+IMPORTANT: WIP
+
+
+Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
+
+To exclude such methods, use the xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] annotation.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
new file mode 100644
index 0000000..175499d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
@@ -0,0 +1,83 @@
+[[how-to-inject-services-into-a-domain-entity-or-other-service]]
+= Injecting services
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib `DomainObjectContainer` is also a service, so can be injected in exactly the same manner.
+
+
+[NOTE]
+====
+Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
+
+If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
+====
+
+
+== Field Injection
+
+Field injection is recommended, using the `@javax.inject.Inject` annotation. For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.inject.Inject
+ OrderRepository orderRepository;
+ ...
+}
+----
+
+
+We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
+
+
+
+
+== Method Injection
+
+Isis also supports two forms of method injection. All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
+of the method does not matter, only that it is prefixed either `set` or `inject`, is
+public, and has a single parameter of the correct type.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ private OrderRepository orderRepository;
+ public void setOrderRepository(OrderRepository orderRepository) {
+ this.orderRepository = orderRepository;
+ }
+ ...
+}
+----
+
+or alternatively, using 'inject' as the prefix:
+
+[source,java]
+----
+public class Customer {
+ private OrderRepository orderRepository;
+ public void injectOrderRepository(OrderRepository orderRepository) {
+ this.orderRepository = orderRepository;
+ }
+ ...
+}
+----
+
+Note that the method name can be anything; it doesn't need to be related to the type being injected.
+
+
+
+
+== Constructor injection
+
+Simply to note that constructor injection is _not_ supported by 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
new file mode 100644
index 0000000..91cec84
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
@@ -0,0 +1,45 @@
+[[_ug_how-tos_class-structure_properties-vs-parameters]]
+= Properties vs Parameters
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+IMPORTANT: WIP
+
+
+In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`. Ideally we want the surname property and surname action parameter to use the same value type.
+
+Having first-class support for this is a goal of Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal. However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as `java.lang.String`.
+
+However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters. It is therefore necessary to use Isis' equivalent annotations for action parameters.
+
+The table below summarises the equivalence of some of the most common cases.
+
+
+.Comparing annotations of Properties vs Action Parameters
+[cols="2,3,3", options="header"]
+|===
+|value type/semantic
+|property
+|action parameter
+
+|string (length)
+|
+|
+
+|big decimal (precision)
+|
+|
+
+|Isis blob
+|
+|
+
+|optional
+|`@Column(allowsNull="true")`
+|`ParameterLayout(optionality=Optionality.OPTIONAL`) or `@Optional`
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
new file mode 100644
index 0000000..c6d9b25
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
@@ -0,0 +1,283 @@
+[[_ug_how-tos_class-structure_properties]]
+= Property
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+IMPORTANT: TODO
+
+
+
+
+
+== Value vs Reference Types
+
+IMPORTANT: WIP
+
+The annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties. The table in the xref:ug.adoc#_ug_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+
+
+
+== Optional Properties
+
+JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc). To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
+
+Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional. These defaults can also be overridden using Isis' own annotations, specifically `@Property(optionality=...)`.
+
+These different defaults can lead to incompatibilities between the two frameworks. To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
+
+For example, rather than:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowNulls="true")
+private LocalDate date;
+@Property(optionality=Optionality.OPTIONAL)
+public LocalDate getDate() { ... }
+public void setDate(LocalDate d) { ... }
+----
+
+you should instead simply write:
+
+[source,java]
+----
+private LocalDate date;
+@javax.jdo.annotations.Column(allowNulls="true")
+public LocalDate getDate() { ... }
+public void setDate(LocalDate d) { ... }
+----
+
+[WARNING]
+====
+With JDO/DataNucleus it's valid for the `@Column` annotation to be placed on either the field or the getter. Apache Isis (currently) only looks for annotations on the getter. We therefore recommend that you always place `@Column` on the gettter.
+====
+
+In all cases the framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
+
+
+
+=== Handling Mandatory Properties in Subtypes
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+ private LocalDate date;
+ @javax.jdo.annotations.Column(allowNulls="true")
+ @Property(optionality=Optionality.MANDATORY)
+ public LocalDate getDate() { ... }
+ public void setDate(LocalDate d) { ... }
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations. Its benefit is that it lumps together all Isis' property metadata in a single annotation. Its downside is that it is rather verbose if the only semantic that needs to be specified -- as is often the case -- is optionality.
+====
+
+An alternative way to achieve this is to leave the JDO annotation on the field (where it is invisible to Isis), and rely on Isis' default, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+ @javax.jdo.annotations.Column(allowNulls="true")
+ private LocalDate date;
+ // mandatory in Isis by default
+ public LocalDate getDate() { }
+ public void setDate(LocalDate d) { }
+}
+----
+
+We recommend the former mapping, though, using `@Property(optionality=Optionality.MANDATORY)`.
+
+
+
+
+
+== ``String``s (Length)
+
+IMPORTANT: TODO
+
+
+
+
+
+[[_ug_how-tos_class-structure_properties_mapping-joda-dates]]
+== Mapping JODA Dates
+
+Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
+
+It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted. See the http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
+
+Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute. To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
+
+For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
+
+
+
+== ``BigDecimal``s (Precision)
+
+Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
+
+For example, suppose we have:
+
+[source,java]
+----
+private BigDecimal impact;
+public BigDecimal getImpact() {
+ return impact;
+}
+public void setImpact(final BigDecimal impact) {
+ this.impact = impact;
+}
+----
+
+JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
+
+What this implies is that, when a record is inserted, a log entry similar to this one appears:
+
+[source,java]
+----
+INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
+----
+
+But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
+
+The solution is to explicitly add the scale to the field like this:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2)
+private BigDecimal impact;
+public BigDecimal getImpact() {
+ return impact;
+}
+public void setImpact(final BigDecimal impact) {
+ this.impact = impact;
+}
+----
+
+In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
+
+More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
+
+
+
+
+== Mapping Blobs and Clobs
+
+Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
+
+As for xref:ug.adoc#_ug_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
+
+=== Mapping Blobs
+
+For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/61b8114a8e01dbb3c380b31cf09eaed456407570/dom/src/main/java/todoapp/dom/module/todoitem/ToDoItem.java#L475[todoapp example app] (non-ASF) the `attachment` property is as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "attachment_name"),
+ @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+ @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "BLOB")
+})
+private Blob attachment;
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() {
+ return attachment;
+}
+public void setAttachment(final Blob attachment) {
+ this.attachment = attachment;
+}
+----
+
+The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that 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 = "BLOB",
+ allowsNull="false")
+})
+private Blob attachment;
+@Property(
+ optionality = Optionality.MANDATORY
+)
+public Blob getAttachment() {
+return attachment;
+}
+public void setAttachment(final Blob attachment) {
+this.attachment = attachment;
+}
+----
+
+=== Mapping Clobs
+
+Mapping `Clob`s works in a very similar way, but the `@Column#sqlType` attribute will be `CLOB`:
+
+[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", sqlType = "CLOB")
+})
+private Clob doc;
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() {
+ return doc;
+}
+public void setDoc(final Clob doc) {
+ this.doc = doc;
+}
+----
+
+
+=== Mapping to VARBINARY or VARCHAR
+
+Instead of mapping to a `Blob` or `Clob` datatype, you might also specify map to a `VARBINARY` or `VARCHAR`. In this case you will need to specify a length. For example:
+
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_bytes", sqlType = "VARBINARY", length=2048)
+----
+
+or
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
+----
+
+Support and maximum allowed length will vary by database vendor.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
new file mode 100644
index 0000000..b45b6fd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
@@ -0,0 +1,69 @@
+[[_ug_how-tos_contributed-members]]
+= Contributed Members
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+IMPORTANT: WIP - generalize to discussion on contributed collections/properties; update to new annotations
+
+Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
+
+For example, given a service:
+
+[source,java]
+----
+public interface Library {
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source,java]
+----
+public class Book implements Loanable { ... }
+----
+
+and
+
+[source,java]
+----
+public class LibraryMember implements Borrower { ... }
+----
+
+then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
+
+This is an important capability because it helps to decouple the concrete classes from the services.
+
+If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
+
+For example:
+
+[source,java]
+----
+public interface Library {
+ @NotContributed
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
+
+Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+
+## Contributed Action
+
+IMPORTANT: TODO
+
+## Contributed Property
+
+IMPORTANT: TODO
+
+## Contributed Collection
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
new file mode 100644
index 0000000..cbe7393
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
@@ -0,0 +1,29 @@
+[[_ug_how-tos_crud]]
+= Object Management (CRUD)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+## Instantiating and Persisting Objects
+
+IMPORTANT: TODO - using ``DomainObjectContainer``'s support for xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-creation-api[creation] and xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-persistence-api[persistence]
+
+## Finding Objects
+
+IMPORTANT: TODO - using xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+
+### Using DataNucleus type-safe queries
+
+IMPORTANT: TODO - as described xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport_type-safe-jdoql-queries[here]
+
+
+
+## Deleting Objects
+
+IMPORTANT: TODO using ``DomainObjectContainer``'s support for xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-persistence-api[persistence]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
new file mode 100644
index 0000000..8c6a8e5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
@@ -0,0 +1,48 @@
+[[_ug_how-tos_derived-members]]
+= Derived Members
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+
+
+== Derived Property
+
+IMPORTANT: TODO
+
+
+
+
+== Derived Collection
+
+IMPORTANT: WIP
+
+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
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`]
+
+
+
+== Trigger on collection change
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
new file mode 100644
index 0000000..cc26c90
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
@@ -0,0 +1,164 @@
+[[_ug_how-tos_domain-services]]
+= Domain Services
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+It's worth extending the <<_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"]
+
+Here, we can see that the addons provide services both to the Isis framework (for example security, command and auditing) and also - by way of dependency injection - to the domain objects (eg tags, excel, settings). Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
+
+The Apache Isis framework also provides numerous in-built domain services. These are catalogued in the reference guide, see xref:rg.adoc#_rg_services-api[here] and xref:rg.adoc#_rg_services-spi[here].
+
+
+
+
+
+== 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:rg.adoc#_rg_annotations_manpage-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
+
+[source,java]
+----
+@javax.enterprise.context.RequestScoped
+public class MyService extends AbstractService {
+ ...
+}
+----
+
+The framework provides a number of request-scoped services, include a scratchpad service, query results caching, and support for co-ordinating bulk actions. See xref:rg.adoc#_rg_services-api[here] and xref:rg.adoc#_rg_services-spi[here] for further details.
+
+
+
+
+== Registering domain services
+
+
+IMPORTANT: TODO - discuss @DomainService if `isis.services-installer=annotation-and-configuration`; how to override these defaults by explicit registration
+
+Domain services (which includes repositories and factories) can be registered 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:rg.adoc#_rg_services-api[here] and _rg_services-spi[here] for further details.
+
+
+
+
+
+== Contributions
+
+IMPORTANT: WIP - just xref xref:ug.adoc#_ug_how-tos_contributed-members[contributed members] section.
+
+
+
+
+
+
+== Menu items
+
+IMPORTANT: WIP - update to new annotations, including @DomainService(nature=...)
+
+
+By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
+
+For example:
+
+[source,java]
+----
+public interface Library {
+ @NotInServiceMenu
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+Alternatively, this can be performed using a supporting method:
+
+[source,java]
+----
+public class LibraryImpl implements Library {
+ public Loan borrow(Loanable l, Borrower b) { ... }
+ public boolean notInServiceMenuBorrow() { ... }
+}
+----
+
+
+
+
+== Menus
+
+IMPORTANT: WIP - update to new annotations, including @DomainService(nature=...)
+
+If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
+
+For example:
+
+[source,java]
+----
+@Hidden
+public interface EmailService {
+ public void sendEmail(String to, String from, String subject, String body);
+ public void forwardEmail(String to, String from, String subject, String body);
+}
+----
+
+
+
+
+== 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 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:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-PreDestroy[`@PreDestroy`].
+
+
+
+
+== The getId() method
+
+Optionally, a service may provide a xref:rg.adoc#_rg_methods_reserved_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
new file mode 100644
index 0000000..0ac05e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
@@ -0,0 +1,65 @@
+[[_ug_how-tos_drop-downs-and-defaults]]
+= Drop Downs and Defaults
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
+== For Properties
+
+IMPORTANT: WIP
+
+### Choices for Property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+
+### Auto-complete for property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+
+### Default for property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
+
+
+
+
+== For Action Parameters
+
+IMPORTANT: WIP
+
+### Choices for action parameter
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+
+### Dependent choices for action params
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+
+### Auto-complete for action param
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+
+### Default for action param
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
+
+
+
+
+
+== For both Properties and Action Parameters
+
+IMPORTANT: WIP
+
+
+### Drop-down for limited number of instances
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`@DomainObject#bounded()`]
+
+
+### Auto-complete (repository-based)
+
+xref:rg.adoc#_rg_annotations_manpage-DomainObject_autoComplete[`@DomainObject#autoComplete()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
new file mode 100644
index 0000000..611946b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
@@ -0,0 +1,15 @@
+[[_ug_how-tos_entity-relationships]]
+= Entity Relationships
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+IMPORTANT: TODO
+
+== Mandatory and Optional
+
+IMPORTANT: TODO
+
+
+include::_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
new file mode 100644
index 0000000..ec5681e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
@@ -0,0 +1,58 @@
+[[_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships]]
+= 1-m bidir relationships
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+When an object is added to a 1:m bidirectional relationship, the child object must refer to the parent and the child must be added to the parent's children collection.
+
+If there were no database involved then we would have recommended that you use the link:http://www.two-sdg.demon.co.uk/curbralan/papers/MutualRegistration.pdf[mutual registration] pattern to ensure that both the parent and child are updated correctly. (The xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`] and xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`] supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern.
+
+However, in a relational database, these two operations in the domain object model correspond simply to updating the foreign key of the child table to reference the parent's primary key.
+
+So long as the parent's children collection is a `java.util.Set` (rather than a `Collection` or a `List`), the JDO Objectstore will automatically maintain both sides of the relationship. All that is necessary is to set the child to refer to the parent.
+
+For example, all you need write is:
+
+[source,java]
+----
+public class Department {
+ @javax.jdo.annotations.Persistent(mappedBy="department") // <1>
+ private SortedSet<Employee> employees = new TreeSet<Employee>();
+
+ public SortedSet<Employee> getEmployees() { ... }
+ public void setEmployees(SortedSet<Employee> employees) { ... }
+ ...
+}
+public class Employee {
+ private Department department;
+ public Department getDepartment() { ... }
+ public void setDepartment(Department department) { ... }
+ ...
+}
+----
+<1> it's the `mappedBy` attribute that tells DataNucleus this is a bidirectional relationship. The value "department" refers to the Employee#department property.
+
+Moreover, when maintaining a bidirectional 1-n relationship that is automatically managed by DataNucleus, it's preferred to "add" to the parent's child collection, don't set the parent on the child.
+
+
+[WARNING]
+====
+If you don't do this then you may (as of Isis 1.4.1) hit an NullPointerException. This may be a bug in DataNucleus, we are not completely sure, but the above idiom seems to fix the issue.
+
+For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the Isis users mailing list, including this http://markmail.org/message/hblptpw675mlw723[message] with the above recommendation.
+====
+
+
+[WARNING]
+====
+In fact, not only do you not need to manually maintain the relationship, we have noted on at least http://markmail.org/message/agnwmzocvdfht32f[one occasion] a subtle error if the code is programmatically added.
+
+The error in that case was that the same object was contained in the parents collection. This of course should not happen for a `TreeSet`. However, JDO/DataNucleus replaces the `TreeSet` with its own implementation, and (either by design or otherwise) this does not enforce `Set` semantics.
+
+The upshot is that you should NEVER programmatically add the child object to the parent's collection if using JDO Objectstore.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
new file mode 100644
index 0000000..62a57b6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
@@ -0,0 +1,15 @@
+[[_ug_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 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::_ug_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_layout.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
new file mode 100644
index 0000000..29c2827
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
@@ -0,0 +1,58 @@
+[[_ug_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
+
+IMPORTANT: WIP - xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
+
+
+Alternatively, you can specify these hints dynamically in the xref:rg.adoc#_rg_object-layout[`Xxx.layout.json`] for the entity.
+
+
+== Per pattern matching
+
+Rather than annotating every action with xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
+
+The xref:ug.adoc#_ug_runtime_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:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:rg.adoc#_rg_annotations_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
new file mode 100644
index 0000000..bf35d00
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
@@ -0,0 +1,58 @@
+[[_ug_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:
+
+IMPORTANT: TODO - screenshot here
+
+For the more commonly used collections we want to show the table expanded:
+
+IMPORTANT: TODO - 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
new file mode 100644
index 0000000..4af7fc5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
@@ -0,0 +1,9 @@
+[[_ug_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:rg.adoc#_rg_object-layout[object layout] chapter.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
new file mode 100644
index 0000000..201b1ee
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
@@ -0,0 +1,47 @@
+[[_ug_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/
+
+IMPORTANT: TODO
+
+
+
+NOTE: see also xref:ug.adoc#_ug_more-advanced_i18n[Internationalization]
+
+== Class (object)
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+
+
+== Property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[`@PropertyLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
+
+
+
+== Collections
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[`@CollectionLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+
+
+
+== Actions
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[`@ActionLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
+
+
+== Action Parameters
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-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:_upgrading_to_java_8_1_9_0_snapshot_and_later[upgrading to Java 8].
+====
+
+
+
+