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 2020/03/21 15:27:54 UTC
[isis] branch master updated: ISIS-2062: more user guide stuff
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 31b6893 ISIS-2062: more user guide stuff
31b6893 is described below
commit 31b68939a82655b7e544c4677b7505a113262a58
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Mar 21 15:27:32 2020 +0000
ISIS-2062: more user guide stuff
---
.../modules/fun/pages/building-blocks/modules.adoc | 2 +-
.../pages/programming-model/domain-services.adoc | 109 +++++++++++++++----
.../fun/pages/programming-model/modules.adoc | 5 +-
.../properties-vs-parameters.adoc | 5 +-
.../fun/pages/programming-model/properties.adoc | 75 ++++++++-----
.../main/adoc/modules/applib-ant/pages/Inject.adoc | 120 ---------------------
.../modules/applib-ant/pages/PostConstruct.adoc | 44 --------
.../adoc/modules/applib-ant/pages/PreDestroy.adoc | 25 -----
.../modules/applib-ant/pages/PropertyLayout.adoc | 1 +
.../adoc/modules/applib-ant/pages/about/jee.adoc | 25 -----
.../modules/applib-ant/partials/module-nav.adoc | 3 -
11 files changed, 140 insertions(+), 274 deletions(-)
diff --git a/api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc b/api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc
index 7580de0..93ca6d3 100644
--- a/api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc
+++ b/api/adoc/userguide/modules/fun/pages/building-blocks/modules.adoc
@@ -30,7 +30,7 @@ The key features that Apache Isis provides to support this are:
* dependency injection of services
+
-Both xref:refguide:applib-svc:about.adoc[framework-defined] domain services and application-defined services (eg repositories and factories) are injected everywhere, using the regular xref:refguide:applib-ant:Inject.adoc[`@javax.inject.Inject`] annotation.
+Both xref:refguide:applib-svc:about.adoc[framework-defined] domain services and application-defined services (eg repositories and factories) are injected everywhere, using the `@javax.inject.Inject` annotation (Spring's `@Autowired` can also be used).
+
By "everywhere", we mean not just into domain services, but _also_ injected into domain entities and view models.
This enables us to implement behaviourally complete domain objects (if we so wish).
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc b/api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc
index d85c41b..b070d9b 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model/domain-services.adoc
@@ -216,46 +216,109 @@ public class SomeClient {
<.> Obtain an instance using `Provider#get()`
-== Registering
+== Configuration
-The easiest way to register domain services with the framework is to use Spring's link:http://localhost:5000[`@ComponentScan`] annotation on an owning link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html[`@Configuration`].
+Spring provides numerous mechanisms to configure domain services, both in terms of binding or passing in the configuration property to the service, and in terms of setting the value within some sort of configuration file.
-The xref:docs:starters:simpleapp.adoc[simpleapp starter apps] illustrates the idiom:
+The mechanism prefered by Apache Isis itself, and which you are free to use for your own services, is the type-safe link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/context/properties/ConfigurationProperties.html[`ConfigurationProperties`], whereby the configuration properties are expressed in a series of nested static classes.
-* for each Maven module, we have
+The xref:docs:starters:simpleapp.adoc[simpleapp starter app] includes an example:
-
-[source,ini]
+[source,java]
----
-public class MyAppManifest implements AppManifest {
- public List<Class<?>> getModules() {
- return Arrays.asList(
- TodoAppDomainModule.class,
- TodoAppFixtureModule.class,
- TodoAppAppModule.class,
- org.isisaddons.module.audit.AuditModule.class);
+import org.springframework.validation.annotation.Validated;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties("app.simple-module")
+@lombok.Data
+@Validated
+public static class Configuration {
+ private final Types types = new Types();
+ @lombok.Data
+ public static class Types {
+ private final Name name = new Name();
+ @lombok.Data
+ public static class Name {
+ private final Validation validation = new Validation();
+ @lombok.Data
+ public static class Validation {
+ private char[] prohibitedCharacters =
+ "!&%$".toCharArray();
+ private String message =
+ "Character '{character}' is not allowed";
+ }
+ }
}
- ...
}
----
-will load all services in the packages underneath the four modules listed.
+This configuration property can be injected, like any other component, and makes the configuration value available in a type-safe fashion:
+
+[source,java]
+----
+val prohibitedCharacters =
+ config.getTypes().getName().getValidation().getProhibitedCharacters();
+----
+
+For this configuration property service to be discovered and managed by Spring, we need to use the link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/context/properties/EnableConfigurationProperties.html[`EnableConfigurationProperties`] annotation.
+This normally would reside on the owning module (discussed in more detail xref:programming-model.adoc#modules[later]):
+
+[source,java]
+.SimpleModule.java
+----
+import org.springframework.context.annotation.Configuration
+
+@Configuration
+// ...
+@EnableConfigurationProperties({
+ SimpleModule.Configuration.class,
+})
+public class SimpleModule /* ... */ {
+ // ...
+}
+----
+
-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:refguide:applib-svc:about.adoc[domain services] reference guide for further details.
+These configuration properties can then be specified using either Spring's `application.yml` or `application.properties`.
+For example:
+
+[source,yml]
+.application.yml
+----
+app:
+ simple-module:
+ types:
+ name:
+ validation:
+ message: "'{character}' is invalid."
+ prohibited-characters: "&%$"
+----
+
+Moreover, Spring is able to configure the IDE so that these configuration values can be specified using code completion.
+All that is required is this dependency:
+
+[source,xml]
+.pom.xml
+----
+<!-- IDE support -->
+<dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-configuration-processor</artifactId>
+ <optional>true</optional>
+</dependency>
+----
== Initialization
-WARNING: TODO: v2: support for init with a Map is no longer supported, I suspect...?
-Instead, can x-ref Spring's strongly typed configuration beans
+Sometimes a domain service needs to perform initialization logic before it is ready to be used.
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+In many cases, such initialization can be performed within the constructor.
+If the initialization has dependencies, then these can be injected using standard link:https://docs.spring.io/spring-boot/docs/current/reference/html/using-spring-boot.html#using-boot-spring-beans-and-dependency-injection[constructor injection].
-An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+Alternatively, initialization can be moved into a `@PostConstruct` link:https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-postconstruct-and-predestroy-annotations[lifecycle callback].
+Shutdown is similar; the framework will call any method annotated with `javax.annotation.PreDestroy`.
-The framework will call any `public` method annotated with xref:refguide:applib-ant:PostConstruct.adoc[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`.
-In the latter case, the framework passes in the configuration.
-Shutdown is similar; the framework will call any method annotated with xref:refguide:applib-ant:PreDestroy.adoc[`@PreDestroy`].
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc b/api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc
index 987e07c..6b1bb44 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model/modules.adoc
@@ -32,10 +32,9 @@ This:
public class IsisModuleSubdomainsExcelApplib {
}
----
-<.> the link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/ComponentScan.html[@ComponentScan].
-This indicates that the classpath should be scanned for domain services, entities and xref:testing:fixtures:about.adoc[fixture scripts].
+<.> the link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/ComponentScan.html[@ComponentScan] indicates that the classpath should be scanned for domain services, entities and xref:testing:fixtures:about.adoc[fixture scripts].
-When there is a dependency, this is expressed in two ways: as a `<dependency` in Maven, and using link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Import.html[@Import] in the "configuration" module.
+When there is a dependency, this is expressed in two ways: first, as a "physical" `<dependency` in Maven; and second, as a "logical" dependency using link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Import.html[@Import] in the `@Configuration` module.
We can see this for example in the `testing` module of the Excel library (artifactId of `isis-submodules-excel-testing`), where:
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/properties-vs-parameters.adoc b/api/adoc/userguide/modules/fun/pages/programming-model/properties-vs-parameters.adoc
index b06040c..b0daa1b 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/properties-vs-parameters.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model/properties-vs-parameters.adoc
@@ -14,7 +14,7 @@ It is therefore necessary to use Apache Isis' equivalent annotations for action
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"]
+[cols="2,3,3",options="header"]
|===
|value type/semantic
|(JDO) property
@@ -34,3 +34,6 @@ The table below summarises the equivalence of some of the most common cases.
|===
+WARNING: TODO: v2 - Meta-annotations; can specify both, those that don't apply are just ignored.
+For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
+The table in the xref:userguide:fun:programming-model.adoc#properties-vs-parameters[Properties vs Parameters] below provides a handy reference of each.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc b/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
index 9026909..10d58b1 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
@@ -4,7 +4,7 @@
:page-partial:
-A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:userguide:fun:programming-model.adoc#view-models[view model].
+A property is an instance variable of a domain object, of a scalar type, that holds some state in either a xref:userguide:fun:programming-model.adoc#domain-entities[domain entity] or a xref:userguide:fun:programming-model.adoc#view-models[view model].
For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
@@ -14,16 +14,18 @@ Formally speaking, a property is simply a regular JavaBean getter, returning a s
Most properties (those that are editable/modifiable) will also have a setter and, if persisted, a backing instance field.
And most properties will also have a number of annotations:
-* Apache Isis defines its own set own `@Property` annotation for capturing domain semantics.
-It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:vw:ROOT:layout.adoc[`.layout.xml`] file)
+* Apache Isis defines its own xref:refguide:applib-ant:Property.adoc[`@Property`] annotation for capturing domain semantics.
+It also provides a xref:refguide:applib-ant:PropertyLayout.adoc[`@PropertyLayout`] for UI hints (though the information in this annotation may instead be provided by a supplementary xref:vw:ROOT:layout.adoc[`.layout.xml`] file)
-* the properties of domain entities are often annotated with the JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
+* the properties of domain entities are usually also annotated with an ORM annotation.
++
+In the case of xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] this would be the link:http://www.datanucleus.org/products/datanucleus/jdo/annotations.html#Column[`@javax.jdo.annotations.Column`] annotation.
For property references, there may be other annotations to indicate whether the reference is bidirectional.
It's also possible (using annotations) to define a link table to hold foreign key columns.
-* for the properties of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElement` may be present
+* for the properties of view models, then JAXB annotations such as link:https://docs.oracle.com/javase/8/docs/api/javax/xml/bind/annotation/XmlElement.html[`@XmlElement`] may 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).
+Apache Isis recognises some of these annotations from the persistence layer and infers some domain semantics from them (for example, the maximum allowable length of a string property).
Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
The xref:docs:starters:simpleapp.adoc[SimpleApp] starter app uses this approach.
@@ -60,16 +62,17 @@ Or to map a reference type:
private Customer customer;
----
-It's ok for a xref:userguide:fun:programming-model.adoc#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).
+It's ok for a xref:userguide:fun:programming-model.adoc#view-models[view model] to reference other view models and also to reference domain entities.
+However, it _isn't_ valid for a domain entity to hold a reference to view model, because the ORM will not know how to persist the view model object.
-[NOTE]
+[TIP]
====
-For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
+For further details on mapping associations using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], see their link:http://www.datanucleus.org:15080/products/accessplatform_5_2/jdo/mapping.html[mapping guide].
====
-For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
-The table in the xref:userguide:fun:programming-model.adoc#properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+== Meta-annotations
+
+WARNING: TODO: v2
== Optional Properties
@@ -101,7 +104,7 @@ rather than the more verbose:
private LocalDate date;
----
-The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
+The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Apache Isis' defaults and DataNucleus, and will refuse to boot if any are found.
== Editable Properties
@@ -117,27 +120,41 @@ For example:
private String notes;
----
-If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:refguide:config:configuring-core.adoc#isis-objects-editing[reference configuration guide] for further details.
+If this is omitted then whether editing is enabled or disabled is inherited from the domain object level, xref:refguide:applib-ant:DomainObject.adoc#editing[`@DomainObject#editing()`].
+
+If that isn't specified (or is set to "AS_CONFIGURED"), then the configuration is taken from the `application.properties` configuration file:
+
+* xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.editing[`isis.applib.annotation.domain-object.editing`]
++
+for all properties in the domain object.
+
+And, finally, if there is no configuration property set at all, then the default is for editing to be DISABLED.
== Ignoring Properties
By default Apache Isis will automatically render all properties in the xref:vw:ROOT:about.adoc[Wicket UI] or in the xref:vro:ROOT:about.adoc[REST API].
-To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
+To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`].
-Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.
+Similarly, for the JDO/DataNucleus ORM, ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.
This is independent of Apache Isis; in other words that property will still be rendered in the UI (unless also annotated with `@Programmatic`).
For view models, you can tell JAXB to ignore a property using the `@javax.xml.bind.annotation.XmlTransient` annotation.
Again, this is independent of Apache Isis.
+You can also suppress a property from the UI using xref:refguide:applib-ant:Property.adoc#hidden[`@Property#hidden()`] or indeed xref:refguide:applib-ant:PropertyLayout.adoc#hidden[`@PropertyLayout#hidden()`].
+However, this doesn't exclude the property from the metamodel.
+
== Derived Properties
Derived properties are those with a getter but no setter.
-Provided that the property has not been annotated with `@Programmatic`, these will still be rendered in the UI, but they will be read-only (not editable) and their state will not be persisted.
+These will still be rendered in the UI, but they will be read-only (not editable).
+
+For entities these may or may not be persisted; that depends on whether the ORM annotations are specified on the field or on the property.
-Subtly different, it is also possible to have non-persisted but still editable properties.
-In this case you will need a getter and a setter, but with the getter annotated using `@NotPersistent`.
-The implementation of these getters and setters will most likely persist state using other properties (which might be hidden from view using `@Programmatic`).
+It's also possible to have non-persisted but still editable properties.
+The setter would not write to a field, but would mutate the object in some other way.
+In such a case you will need a getter and a setter, but with the field/property annotated for the ORM as non-persistent.
+If using JDO/DataNucleus, this is done using `@NotPersistent`.
For example:
@@ -146,24 +163,24 @@ For example:
@javax.jdo.annotations.NotPersistent
@Property(editing=Editing.ENABLED)
public String getAddress() {
- return addressService.toAddress( getLatLong() ); // <1>
+ return addressService.toAddress( getLatLong() ); // <.>
}
public void setAddress(String address) {
setLatLong(addressService.toLatLong(address));
}
-@javax.jdo.annotations.Column
-private String latLong;
@Programmatic
-public String getLatLong() { return latLong; } // <2>
-public void setLatLong(String latLong) { this.latLong = latLong; }
+@lombok.Getter @lombok.Setter
+@javax.jdo.annotations.Column
+private String latLong; // <.>
@javax.inject.Inject
-AddressService addressService; // <3>
+AddressService addressService; // <.>
----
-<1> the representation of the address, in human readable form, eg "10 Downing Street, London, UK"
-<2> the lat/long representation of the address, eg "51.503363;-0.127625"
-<3> an injected service that can convert to/from address and latLong.
+<.> the representation of the address, in human readable form, eg "10 Downing Street, London, UK"
+<.> the lat/long representation of the address, eg "51.503363;-0.127625".
+Excluded from the Apache Isis metamodel.
+<.> an injected service that can convert to/from address and latLong.
== Data types
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc
deleted file mode 100644
index a675894..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Inject.adoc
+++ /dev/null
@@ -1,120 +0,0 @@
-r= `@Inject` (`javax`)
-
-: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 ag [...]
-
-
-
-Apache Isis automatically injects domain services into other domain services and also into domain objects and view models.
-In fact, it also injects domain services into xref:testing:integtestsupport:about.adoc[integration tests] and xref:fixtures:ROOT:about.adoc[fixture scripts].
-
-
-Apache Isis supports several syntaxes for injecting domain services.
-The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public List<Order> findRecentOrders() { // <1>
- return orders.recentOrdersFor(this);
- }
- @javax.inject.Inject
- OrderRepository orders; // <2>
-}
-----
-<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:userguide:fun:programming-model.adoc#contributed-action[contributed action].
-<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
-
-== Alternative syntaxes
-
-Apache Isis also supports setter-based injection:
-
-[source,java]
-----
-public class Customer {
- ...
- public void setOrderRepository(OrderRepository orderRepository) { /* ... */ }
-}
-----
-
-
-Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
-
-== Injecting collection of services
-
-It can sometimes be useful to have declared multiple implementations of a particular domain service.
-For example, you may have a module that defines an SPI service, where multiple other modules might provide implementations of that SPI (akin to the chain of responsibility pattern).
-To support these scenarios, it is possible to annotate a `List` or `Collection`.
-
-For example, suppose that we provide an SPI service to veto the placing of ``Order``s for certain ``Customer``s:
-
-[source,java]
-----
-public interface CustomerOrderAdvisorService {
- @Programmatic
- String vetoPlaceOrder(Customer c);
-----
-
-We could then inject a collection of these services:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(Product p, int quantity) { /* ... */ }
- public String disablePlaceOrder(Product p, int quantity) {
- for(CustomerOrderAdvisorService advisor: advisors) {
- String reason = advisor.vetoPlaceOrder(this);
- if(reason != null) { return reason; }
- }
- return null;
- }
- @Inject
- Collection<CustomerOrderAdvisorService> advisors; // <1>
-}
-----
-<1> inject a collection of the services.
-
-[NOTE]
-====
-An alternative and almost equivalent design would be to publish an event using the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and implement the domain services as subscribers to the event.
-This alternative design is used in the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s poly module, for example.
-====
-
-== Manually injecting services
-
-Apache Isis performs dependency injection when domain entities are recreated.
-It will also perform dependency injection if an object is created through the xref:refguide:applib-svc:FactoryService.adoc[`FactoryService`] or xref:refguide:applib-svc:RepositoryService.adoc[`RepositoryService`].
-
-For example, to create a new (transient) domain object, the idiom is:
-
-[source,java]
-----
-Customer cust = repositoryService.instantiate(Customer.class); <1>
-// initialize state of "cust"
-repositoryService.persist(cust);
-----
-
-View models are created identically:
-
-[source,java]
-----
-TodoAppDashboard dashboard = repositoryService.instantiate(TodoAppDashboard.class);
-----
-
-If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually using xref:refguide:applib-svc:ServiceRegistry.adoc[`ServiceRegistry`]:
-
-[source,java]
-----
-Customer cust = new Customer();
-serviceRegistry.injectServicesInto(cust);
-// initialize state of "cust"
-repositoryService.persist(cust);
-----
-
-[NOTE]
-====
-Note that using either `FactoryService#instantiate(...)` or `RepositoryService#instantiate(...)` will also automatically initialize all fields to their default values, and will also fire a "created" lifecycle event.
-
-Neither of these are particularly useful (and indeed can sometimes be rather confusing) so you may well wish to standardize on using `injectServicesInto(...)` throughout.
-====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PostConstruct.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PostConstruct.adoc
deleted file mode 100644
index d13c599..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PostConstruct.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-= `@PostConstruct` (`javax`)
-
-: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 ag [...]
-
-WARNING: TODO: v2 - the init with args is no longer supported; instead use IsisConfiguration injected or any Spring Boot `@ConfigurationProperties` class.
-
-The `@javax.annotation.PostConstruct` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250], is recognized by Apache Isis as a callback method on domain services to be called just after they have been constructed, in order that they initialize themselves.
-
-It is also recognized for xref:userguide:fun:building-blocks.adoc#view-models[view models] (eg annotated with xref:refguide:applib-ant:ViewModel.adoc[`@ViewModel`]).
-
-For the default application-scoped (singleton) domain services, this means that the method, if present, is called during the bootstrapping of the application.
-For xref:refguide:applib-ant:IsisSessionScope.adoc[`@IsisSessionScope`] domain services, the method is called at the beginning of the request.
-
-The signature of the method is:
-
-[source,java]
-----
-@PostConstruct <1>
-public void init() { /* ... */ } <2>
-----
-<1> It is not necessary to annotate the method with xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
-<2> the method can have any name, but must have `public` visibility.
-
-In the form shown above the method accepts no arguments.
-Alternatively - for domain services only, not view models - the method can accept a parameter of type `Map<String,String>`:
-
-[source,java]
-----
-@PostConstruct
-@Programmatic
-public void init(Map<String,String> properties) { /* ... */ }
-----
-
-Apache Isis uses argument to pass in the configuration properties read from all xref:refguide:config:configuration-files.adoc[configuration files]:
-
-[TIP]
-====
-Alternatively, you could inject xref:refguide:applib-svc:ConfigurationService.adoc[`ConfigurationService`] into the service and read configuration properties using `ConfigurationService#getProperty(...)` and related methods.
-However, be aware when using this latter API that only those configuration properties keys with an `application.` prefix are provided.
-====
-
-Use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.
-
-See also xref:refguide:applib-ant:PreDestroy.adoc[`@PreDestroy`]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc
deleted file mode 100644
index 1e67028..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PreDestroy.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-= `@PreDestroy` (`javax`)
-
-: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 ag [...]
-
-
-
-The `@javax.annotation.PreDestroy` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250], recognized by Apache Isis as a callback method on domain services to be called just as they go out of scope.
-
-For the default application-scoped (singleton) domain services, this means that the method, if present, is called just prior to the termination of the application.
-For xref:refguide:applib-ant:IsisSessionScope.adoc[`@IsisSessionScope`] domain services, the method is called at the end of the request.
-
-The signature of the method is:
-
-[source,java]
-----
-@PreDestroy <.>
-public void deinit() { /* ... */ } <.>
-----
-
-<.> It is not necessary to annotate the method with xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
-<.> the method can have any name, but must have `public` visibility, and accept no arguments.
-
-Other use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.
-
-See also xref:refguide:applib-ant:PostConstruct.adoc[`@PostConstruct`]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
index 0dba772..3768870 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout.adoc
@@ -117,6 +117,7 @@ so that boilerplate-busting tools such as link:https://projectlombok.org/[Projec
include::PropertyLayout/cssClass.adoc[leveloffset=+1]
include::PropertyLayout/describedAs.adoc[leveloffset=+1]
+include::PropertyLayout/hidden.adoc[leveloffset=+1]
include::PropertyLayout/labelPosition.adoc[leveloffset=+1]
include::PropertyLayout/multiLine.adoc[leveloffset=+1]
include::PropertyLayout/named.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc
index 7b0947f..c3abd96 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/about/jee.adoc
@@ -31,11 +31,6 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|Domain
|
-|xref:refguide:applib-ant:Inject.adoc[`@javax.inject.` +
-`Inject`]
-|Inject domain service into a domain object (entity or view model) or another domain service.
-|Domain
-|
|xref:refguide:applib-ant:Digits.adoc[`@javax.annotation.` +
`Nullable`]
@@ -43,26 +38,6 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|Domain
|
-|xref:refguide:applib-ant:PostConstruct.adoc[`@javax.annotation.` +
-`PostConstruct`]
-|Callback for domain services (either singleton or xref:refguide:applib-ant:IsisSessionScope.adoc[request-scoped]) to initialize themselves once instantiated.
-
-|Domain
-|
-
-|xref:refguide:applib-ant:PreDestroy.adoc[`@javax.annotation.` +
-`PreDestroy`]
-|Callback for domain services (either singleton or xref:refguide:applib-ant:IsisSessionScope.adoc[request-scoped]) to clean up resources prior to destruction.
-
-|Domain
-|
-
-|xref:refguide:applib-ant:RequestScoped.adoc[`@javax.enterprise.` +
-`context.` +
-`RequestScoped`]
-|Specify that a domain service has request-scope (rather than a singleton).
-|Domain
-|
|xref:refguide:applib-ant:XmlRootElement.adoc[`javax.xml.bind` +
`.annotation` +
diff --git a/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc b/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
index 7733b27..e7cd240 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
@@ -16,7 +16,6 @@
** xref:refguide:applib-ant:DomainServiceLayout.adoc[DomainServiceLayout]
** xref:refguide:applib-ant:Facets.adoc[Facets]
** xref:refguide:applib-ant:HomePage.adoc[HomePage]
-** xref:refguide:applib-ant:Inject.adoc[Inject]
** xref:refguide:applib-ant:MemberOrder.adoc[MemberOrder]
** xref:refguide:applib-ant:Mixin.adoc[Mixin]
** xref:refguide:applib-ant:NotPersistent.adoc[NotPersistent.]
@@ -26,8 +25,6 @@
** xref:refguide:applib-ant:ParameterLayout.adoc[ParameterLayout]
** xref:refguide:applib-ant:Pattern.adoc[Pattern]
** xref:refguide:applib-ant:PersistenceCapable.adoc[PersistenceCapable]
-** xref:refguide:applib-ant:PostConstruct.adoc[PostConstruct]
-** xref:refguide:applib-ant:PreDestroy.adoc[PreDestroy]
** xref:refguide:applib-ant:PrimaryKey.adoc[PrimaryKey]
** xref:refguide:applib-ant:Programmatic.adoc[Programmatic]
** xref:refguide:applib-ant:Property.adoc[Property]