You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/04/20 08:12:31 UTC
[22/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
deleted file mode 100644
index 25b27db..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
+++ /dev/null
@@ -1,229 +0,0 @@
-[[_ugfun_domain-class-ontology_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 fit in:
-
-.The hexagonal architecture with Isis addons
-image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
-
-The (non-ASF) link:http://isisaddons.org[Isis Addons] provide SPI implementations of the common cross-cutting concerns.
-They also provide a number of APIs for domain objects to invoke (not shown in the diagram).
-You can also write your own domain services as well, for example to interface with some external CMS system, say.
-
-
-
-[[__ugfun_domain-class-ontology_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.
-
-
-[[__ugfun_domain-class-ontology_domain-services_factory-and-repository]]
-== Factory and Repository
-
-The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] 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 repositoyService.allMatches(...);
- }
- public Customer newCustomer(...) {
- Customer Customer = container.newTransientInstance(Customer.class);
- ...
- persistIfNotAlready(Customer);
- return Customer;
- }
- public List<Customer> allCustomers() {
- return repositoryService.allInstances(Customer.class);
- }
- @Inject
- RepositoryService repositoryService;
-}
-----
-<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.
-
-
-[[__ugfun_domain-class-ontology_domain-services_menu]]
-== 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.
-====
-
-
-
-[[__ugfun_domain-class-ontology_domain-services_contributions]]
-== Contributions (deprecated)
-
-
-Services can contribute either actions, properties or collections, based on the type of their parameters.
-
-[TIP]
-====
-Contributed services can instead be implemented as
-xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins].
-As such, contributed services should be considered as deprecated.
-====
-
-We suggest naming such classes `XxxContributions`, eg:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY // <1>
-)
-@DomainServiceLayout(
- menuOrder="10",
- name="...",
-}
-public class 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].
-
-
-
-
-[[__ugfun_domain-class-ontology_domain-services_event-subscribers]]
-== 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 class 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_domain-class-ontology_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.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
deleted file mode 100644
index 0acc6cb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-[[_ugfun_domain-class-ontology_mixins]]
-= Mixins
-: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 mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model.
-
-Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own syntax for defining such constructs.
-In Apache Isis a mixin is very similar to a domain service, however it also defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.
-
-Why do this?
-Two reasons:
-
-* The main reason is to allow the app to be decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
-Mixins (and contributions) allow dependency to be inverted, so that the dependencies between modules can be kept acyclic and under control.
-
-* However, there is another reason: mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
-
-Both use cases are discussed below.
-
-Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
-
-
-
-[source,java]
-----
-@Mixin(method="coll") // <1>
-public class Customer_orders { // <2>
-
- private final Customer customer;
- public Customer_orders(final Customer customer) { // <3>
- this.customer = customer;
- }
-
- @Action(semantics=SemanticsOf.SAFE) // <4>
- @ActionLayout(contributed=Contributed.AS_ASSOCIATION) // <4>
- @CollectionLayout(render=RenderType.EAGERLY)
- public List<Order> coll() { // <1>
- return repositoryService.findOrdersFor(customer);
- }
-
- @Inject
- RepositoryService repositoryService;
-}
-----
-<1> indicates that this is a mixin, with "coll" as the name of the main method
-<2> The contributed member is inferred from the name, after the "_"; in other words "orders"
-<3> The mixee is `Customer`.
-This could also be an interface.
-<4> Indicates that the action should be interpreted as a collection.
-This requires that the action has safe semantics, ie does not alter state/no side-effects.
-
-There is further discussion of mixins in the xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[beyond the basics] guide.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
deleted file mode 100644
index 4e510ac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
+++ /dev/null
@@ -1,196 +0,0 @@
-[[_ugfun_domain-class-ontology_view-models]]
-= View Models
-: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/
-
-
-
-View models 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.
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-`Customer`, `Order`, `Product`, and so on.
-
-For some applications this may well suffice. However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities, to view models.
-This section explores these use cases.
-
-
-
-
-[[__ugfun_domain-class-ontology_view-models_externally-managed-entities]]
-== Externally-managed entities
-
-Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
-but reside in some other system, for example accessible only through a SOAP web service. Logically that data
-might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
-modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
-update it.
-
-There are a couple of ways around this: we could either replicate the data somehow from the external system into the
- Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
- the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an
- external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
-
-The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
-
-[NOTE]
-====
-DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
-could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
-
-An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
-implementing one that also supported updating external entities would need to carefully consider error conditions if the
-external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
-desirable in any case).
-====
-
-
-[[__ugfun_domain-class-ontology_view-models_in-memory-entities]]
-== In-memory entities
-
-As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
-state is not actually persisted anywhere, merely held in-memory (eg in a hash).
-
-A simple example might be read-only configuration data that is read from a config file (eg log4j appender
-definitions) but thereafter is presented in the UI just like any other entity.
-
-
-[[__ugfun_domain-class-ontology_view-models_application-layer-view-models]]
-== Application-layer view models
-
-Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
-solid. Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain. These domain entities are part of the domain layer.
-
-That said, it may not always be practical to expect end-users of the application to interact solely with those domain
-entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user,
-often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by
- querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
- the end user.
-
-A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
- model. It is not a persisted entity, instead it belongs to the application layer.
-
-A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will
-be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in
-some cases such view model actions might also modify state of underlying domain entities.
-
-Another common use for view models is to help co-ordinate complex business processes; for example to perform a
-quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model
-might have some state of its own, but in most cases that state does not need to be persisted per se.
-
-.Desire Lines
-****
-One way to think of application view models is as modelling the "desire line": the commonly-trod path
-that end-users must follow to get from point A to point B as quickly as possible.
-
-To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
-link:https://sivers.org/walkways[examples]
-link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
-campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
-routes they want to take. The name we like best for this idea is "desire lines", though it has also been called
-a "desire path", "paving the path" or "paving the sidewalk".
-
-What that means is you should add view models _after_ having built up the domain layer, rather than before. These view
-models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
-
-It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
-what the use cases are that those domain entities are trying to support. You certainly _shouldn't_ try to build out a
-domain layer that could support every conceivable use case before starting to think about view models.
-
-Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
-business. Then build out the minimum domain entities to support that use case (refining the xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
-go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
-with the system (perhaps automating several related use cases together).
-****
-
-[[__ugfun_domain-class-ontology_view-models_dtos]]
-== DTOs
-
-DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carry data between processes".
-
-If those two processes are parts of the same overall application (the same team builds and deploys both server and
-client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
-xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
-
-On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
-a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over xref:../ugvro/ugvro.adoc#[RestfulObjects] would be
-"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
-easily changed by the producer.
-
-To support this use case, a view model can be defined such that it can act as a DTO. This is done by annotating the
-class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
-XSD schema describing the structure of that XML. A discussion of how that might be done using an ESB such as
-link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugfun_domain-class-ontology_view-models_dtos_consumers[below].
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other. In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
-
-
-It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
-The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
-framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
-
-
-[[__ugfun_domain-class-ontology_view-models_dtos_consumers]]
-=== DTO Consumers
-
-The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
-eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
-such as Apache Camel.
-
-In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
-An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
-used to return the appropriate DTO (as XML).
-
-For the latter case, one design is simply for the application to instantiate the view model, then call the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML. This can then be published onto
-the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
-
-However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
- (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only
- the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required. This can once again be done by calling the REST API with
- an appropriate HTTP `Accept` header.
-
-[TIP]
-====
-This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate). In our case we focus on the validation (to determine the nature of the inbound message, ie which action was
-invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
-====
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design. It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
-but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
-queue. Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
-parse the action memento to determine what has changed on the source system. Thereafter, a subsequent Camel processor
-can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with
-additional details using a DTO.
-
-
-
-
-
-[[__ugfun_domain-class-ontology_view-models_typical-implementation]]
-== Typical Implementation
-
-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/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
new file mode 100644
index 0000000..98fcff1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
@@ -0,0 +1,91 @@
+[[_ugfun_programming-model]]
+= Programming Model
+: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, domain services, view models and mixins.
+Dependent on the sort of domain object, the class methods represent
+both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.
+
+More specifically, both entities and view models can have properties, collections and actions, while domain services have just actions.
+Mixins also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
+
+In the automatically generated UI a property is rendered as a field.
+This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.
+A collection is generally rendered as a table.
+
+In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.
+This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
+
+Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
+
+In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
+
+[TIP]
+====
+In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.
+The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
+
+You can learn more about extending Apache Isis programming model xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[here].
+====
+
+
+The Apache Isis programming model uses annotations to distinguish these object types:
+
+* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel` (which is used is a matter of personal preference); the framework will automatically manage the view model's state (properties only, not collections). +
++
+Or, they can be annotated using the JAXB `@XmlTypeAdapter` annotation, which allows the view models' properties _and_ collections state to be managed.
+
+* *domain entities* that are persisted to the database (as the vast majority will) are annotated with `@DomainObject(nature=ENTITY)`.
+In addition such domain entities are annotated with the JDO/DataNucleus annotation of
+`@javax.jdo.annotations.PersistenceCapable`. +
++
+In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used. +
++
+These entities' state is managed by the framework, in the same ways as view models.
+Indeed, they can additionally be annotated using `@XmlTypeAdapter` if required.
+
+* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`.
+As for view models, which is used is a matter of personal preference.
+
+* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either `VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY` (for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
+functionality is simply for other domain objects to invoke programmatically).
++
+It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
+This is in fact the default, useful for initial prototyping.
+A final nature is `VIEW_REST_ONLY` which is for domain services whose functionality is surfaced only by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
+
+You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
+
+It's worth emphasising is that domain entities and view models hold state, whereas domain services are generally stateless.
+If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be `@RequestScoped` so that this state is short-lived and usable only within a single request.
+
+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.
+
+
+
+
+include::_ugfun_programming-model_domain-entities.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_domain-services.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_view-models.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_mixins.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_properties.adoc[leveloffset=+1]
+include::_ugfun_programming-model_collections.adoc[leveloffset=+1]
+include::_ugfun_programming-model_actions.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_inject-services.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_properties-vs-parameters.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc
new file mode 100644
index 0000000..80f657a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc
@@ -0,0 +1,264 @@
+[[_ugfun_programming-model_actions]]
+= Actions
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+While xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties] and xref:../ugfun/ugfun.adoc#_ugfun_programming-model_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
+
+An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
+Such applications are often called CRUD applications (create/read/update/delete).
+
+In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
+So instead actions allow those business rules to be encoded programmatically.
+An Apache Isis application doesn't try to constrain the end-user as to way in which they interact with the user (it doesn't attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren't allowed to go into an invalid state.
+
+For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
+But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
+Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
+If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
+But if the state change is more complex, then most likely an action should be used instead.
+
+
+[[__ugfun_programming-model_actions_defining-actions]]
+== Defining actions
+
+Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
+This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:../ugfun/ugfun.adoc#_ugfun_business-rules[business rules]); these also not treated as actions.
+And, any method that are annotated with `@Programmatic` will also be excluded.
+But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
+
+For example:
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT) // <1>
+public ShoppingBasket addToBasket(
+ Product product,
+ @ParameterLayout(named="Quantity") // <2>
+ int quantity
+ ) {
+ ...
+ return this;
+}
+----
+<1> `@Action` annotation is optional but used to specify additional domain semantics (such as being idempotent).
+<2> The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
+For the `product` parameter this is reasonable, but not so for the `quantity` parameter (which would by default show up with a name of "int".
+The `@ParameterLayout` annotation provides a UI hint to the framework.
+
+[TIP]
+====
+The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8[paraname8] metamodel extension allows the parameter name to be used in the UI, rather than the type.
+====
+
+
+[[__ugfun_programming-model_actions_reference-parameter-types]]
+== (Reference) Parameter types
+
+Parameter types can be value types or reference types.
+In the case of primitive types, the end-user can just enter the value directly through the parameter field.
+In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
+This is done using either a supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
+The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
+
+For example, the `addToBasket(...)` action shown above might well have a :
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)
+public ShoppingBasket addToBasket(
+ Product product,
+ @ParameterLayout(named="Quantity")
+ int quantity
+ ) {
+ ...
+ return this;
+}
+public List<Product> autoComplete0AddToBasket( // <1>
+ @MinLength(3) // <2>
+ String searchTerm) {
+ return productRepository.find(searchTerm); // <3>
+}
+@javax.inject.Inject
+ProductRepository productRepository;
+----
+<1> Supporting `autoComplete` method.
+The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
+It is also required to return a Collection of that type.
+<2> The xref:../rgant/rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
+<3> The implementation delegates to an injected repository service. This is typical.
+
+Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
+
+[[__ugfun_programming-model_actions_reference-parameter-types_removing-boilerplate]]
+=== Removing boilerplate
+
+To save having to define an `autoCompleteNXxx(...)` method everywhere that a reference to a particular type (such as `Product`) appears as an action parameter, it is also possible to use the `@DomainObject` annotation on `Product` itself:
+
+[source,java]
+----
+@DomainObject(
+ autoCompleteRepository=ProductRepository.class // <1>
+ autoCompleteAction="find" // <2>
+)
+public class Product ... {
+ ...
+}
+----
+<1> Whenever an action parameter requiring a `Product` is defined, provide an autoComplete drop-down automatically
+<2> Use the "find" method of `ProductRepository` (rather than the default name of "autoComplete")
+
+(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the `choicesNXxx()` supporting method can be used.
+This too can be avoided by annotating the referenced class.
+
+For example, suppose we have an action to specify the `PaymentMethodType`, where there are only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
+We could define this as:
+
+[source,java]
+----
+public Order payUsing(PaymentMethodType type) {
+ ...
+}
+----
+
+where `PaymentMethodType` would be annotated using:
+
+[source,java]
+----
+@DomainObject(
+ bounded=true // <1>
+)
+public class PaymentMethodType ... {
+ ...
+}
+----
+<1> only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.
+
+
+[[__ugfun_programming-model_actions_collection-parameter-types]]
+== Collection Parameter types
+
+Action parameters can also be collections of values (for example `List<String>`), or can be collections of references (such as `List<Customer>`).
+
+For example:
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)
+public ShoppingBasket addToBasket(
+ List<Product> products,
+ @ParameterLayout(named="Quantity") int quantity
+ ) {
+ ...
+ return this;
+}
+public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
+ return ...
+}
+----
+
+As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:../rgant/rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:../ugfun/ugfun.adoc#__ugfun_programming-model_actions_reference-parameter-types_removing-boilerplate[above]).
+
+
+[[__ugfun_programming-model_actions_optional-parameters]]
+== Optional Parameters
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_optional-properties[optionality of properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
+Instead, either the xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true") // <1>
+@lombok.Getter @lombok.Setter
+private LocalDate shipBy;
+
+public Order invoice(
+ PaymentMethodType paymentMethodType,
+ @Nullable // <2>
+ @ParameterLayout(named="Ship no later than")
+ LocalDate shipBy) {
+ ...
+ setShipBy(shipBy)
+ return this;
+}
+----
+<1> Specifies the property is optional.
+<2> Specifies the corresponding parameter is optional.
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[properties vs parameters].
+
+[[__ugfun_programming-model_actions_string-parameters]]
+== ``String`` Parameters (Length)
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_datatypes_strings[length of string properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(length=50) // <1>
+@lombok.Getter @lombok.Setter
+private String firstName;
+
+@javax.jdo.annotations.Column(length=50)
+@lombok.Getter @lombok.Setter
+private String lastName;
+
+public Customer updateName(
+ @Parameter(maxLength=50) // <2>
+ @ParameterLayout(named="First name")
+ String firstName,
+ @Parameter(maxLength=50)
+ @ParameterLayout(named="Last name")
+ String lastName) {
+ setFirstName(firstName);
+ setLastName(lastName);
+ return this;
+}
+----
+<1> Specifies the property length using the JDO xref:../rgant/rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
+<2> Specifies the parameter length using the (Apache Isis) xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
+
+[IMPORTANT]
+====
+Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply set the instance field directly.
+This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
+====
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[properties vs parameters].
+
+[[__ugfun_programming-model_actions_bigdecimal-parameters]]
+== ``BigDecimal``s (Precision)
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_datatypes_bigdecimals[precision of BigDecimal properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2) // <1>
+@lombok.Getter @lombok.Setter
+private BigDecimal discountRate;
+
+public Order updateDiscount(
+ @javax.validation.constraints.Digits(fraction=2) // <2>
+ @ParameterLayout(named="Discount rate")
+ String discountRate) {
+ setDiscountRate(discountRate);
+ return this;
+}
+----
+<1> Specifies the property precision using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
+<2> Specifies the corresponding parameter precision using xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[properties vs parameters].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
new file mode 100644
index 0000000..8a7aafe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
@@ -0,0 +1,121 @@
+[[_ugfun_programming-model_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_programming-model_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_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_programming-model_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_programming-model_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.
+
+
+
+[[__ugfun_programming-model_collections_mapping-bidir-1m]]
+== 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#_ugbtb_hints-and-tips_simulating-collections-of-values[elsewhere].
+
+
+
+[[__ugfun_programming-model_collections_derived-collections]]
+== Derived Collections
+
+A derived collection is simply a getter (no setter) that returns a `java.util.Collection` (or subtype).
+
+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);
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
new file mode 100644
index 0000000..ad2bd72
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
@@ -0,0 +1,89 @@
+[[_ugfun_programming-model_domain-entities]]
+= Domain Entities
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+Entities are persistent domain objects, with their persistence handled by JDO/DataNucleus.
+As such, they are mapped to a persistent object store, typically an RDBMS, with DataNucleus taking care of both lazy loading and also the persisting of modified ("dirty") objects.
+
+Domain entities are generally 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.
+
+
+NOTE: FIXME - xref the ugodn guide for other mappings of persistent entities.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
new file mode 100644
index 0000000..68f8919
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
@@ -0,0 +1,383 @@
+[[_ugfun_programming-model_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/
+
+
+This section looks at the programming conventions of writing your own domain services.
+
+''''
+''''
+
+[[__ugfun_building-blocks_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
+
+NOTE: FIXME - deprecate any mention of VIEW_CONTRIBUTIONS_ONLY
+
+Pulling all the above together, here are our suggestions as to how you should organize your domain services.
+
+NOTE: FIXME - instead, xref to progamming model sections
+
+
+
+
+== Prototyping
+
+While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_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.
+
+
+
+
+
+''''
+''''
+
+
+== Typical Implementation
+
+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_programming-model_inject-services[below].
+
+
+
+''''
+''''
+
+
+
+[[__ugfun_building-blocks_domain-services_factory-and-repository]]
+== Factory and Repository
+
+The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] 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 repositoyService.allMatches(...);
+ }
+ public Customer newCustomer(...) {
+ Customer Customer = container.newTransientInstance(Customer.class);
+ ...
+ persistIfNotAlready(Customer);
+ return Customer;
+ }
+ public List<Customer> allCustomers() {
+ return repositoryService.allInstances(Customer.class);
+ }
+ @Inject
+ RepositoryService repositoryService;
+}
+----
+<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.
+
+
+[[__ugfun_building-blocks_domain-services_menu]]
+== 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.
+====
+
+
+
+[[__ugfun_building-blocks_domain-services_contributions]]
+== Contributions (deprecated)
+
+
+Services can contribute either actions, properties or collections, based on the type of their parameters.
+
+[TIP]
+====
+Contributed services can instead be implemented as
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
+As such, contributed services should be considered as deprecated.
+====
+
+We suggest naming such classes `XxxContributions`, eg:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY // <1>
+)
+@DomainServiceLayout(
+ menuOrder="10",
+ name="...",
+}
+public class 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].
+
+
+
+
+[[__ugfun_building-blocks_domain-services_event-subscribers]]
+== Event Subscribers
+
+NOTE: FIXME - use AbstractSubscriber, need to show how to subscribe with event service bus...
+
+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 class 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
+
+
+
+
+''''
+''''
+
+
+
+== 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/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc
new file mode 100644
index 0000000..1e23b09
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc
@@ -0,0 +1,103 @@
+[[_ugfun_programming-model_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).
+
+
+
+
+
+