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/27 00:44:04 UTC
[isis] branch ISIS-2062 updated: ISIS-2062: refguide (annotations)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2062
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/ISIS-2062 by this push:
new 69b8c63 ISIS-2062: refguide (annotations)
69b8c63 is described below
commit 69b8c63cdb147105f71f0227d4c089485b0fb671
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Mar 27 00:43:45 2020 +0000
ISIS-2062: refguide (annotations)
---
.../how-to-handle-void-and-null-results.adoc | 2 +-
.../replacing-default-service-implementations.adoc | 4 +-
.../modules/fun/pages/drop-downs-and-defaults.adoc | 2 +-
.../main/adoc/modules/applib-ant/pages/Action.adoc | 1 +
.../modules/applib-ant/pages/ActionLayout.adoc | 1 +
.../adoc/modules/applib-ant/pages/Collection.adoc | 1 +
.../applib-ant/pages/Collection/editing.adoc | 15 +++--
.../applib-ant/pages/Collection/hidden.adoc | 16 ++---
.../pages/Collection/mementoSerialization.adoc | 11 +++-
.../applib-ant/pages/Collection/typeOf.adoc | 10 +--
.../modules/applib-ant/pages/CollectionLayout.adoc | 1 +
.../pages/CollectionLayout/cssClass.adoc | 15 ++---
.../pages/CollectionLayout/defaultView.adoc | 32 ++++-----
.../pages/CollectionLayout/describedAs.adoc | 16 +++--
.../applib-ant/pages/CollectionLayout/hidden.adoc | 17 +++--
.../applib-ant/pages/CollectionLayout/named.adoc | 16 ++---
.../applib-ant/pages/CollectionLayout/paged.adoc | 19 +++---
.../pages/CollectionLayout/sortedBy.adoc | 36 +++++-----
.../main/adoc/modules/applib-ant/pages/Column.adoc | 1 +
.../main/adoc/modules/applib-ant/pages/Digits.adoc | 1 +
.../modules/applib-ant/pages/Discriminator.adoc | 3 +-
.../modules/applib-ant/pages/DomainObject.adoc | 1 +
.../pages/DomainObject/actionDomainEvent.adoc | 16 ++---
.../applib-ant/pages/DomainObject/auditing.adoc | 6 +-
.../pages/DomainObject/autoCompleteRepository.adoc | 28 +++-----
.../applib-ant/pages/DomainObject/bounding.adoc | 8 +--
.../pages/DomainObject/collectionDomainEvent.adoc | 26 ++++----
.../pages/DomainObject/createdLifecycleEvent.adoc | 10 +--
.../applib-ant/pages/DomainObject/editing.adoc | 23 ++-----
.../pages/DomainObject/loadedLifecycleEvent.adoc | 15 ++---
.../applib-ant/pages/DomainObject/mixinMethod.adoc | 33 ++++++----
.../applib-ant/pages/DomainObject/nature.adoc | 17 ++---
.../applib-ant/pages/DomainObject/objectType.adoc | 8 +--
.../DomainObject/persistedLifecycleEvent.adoc | 17 ++---
.../DomainObject/persistingLifecycleEvent.adoc | 18 ++---
.../pages/DomainObject/propertyDomainEvent.adoc | 5 +-
.../applib-ant/pages/DomainObject/publishing.adoc | 4 +-
.../pages/DomainObject/removingLifecycleEvent.adoc | 19 ++----
.../pages/DomainObject/updatedLifecycleEvent.adoc | 18 ++---
.../pages/DomainObject/updatingLifecycleEvent.adoc | 18 ++---
.../applib-ant/pages/DomainObjectLayout.adoc | 1 +
.../pages/DomainObjectLayout/bookmarking.adoc | 19 +++---
.../pages/DomainObjectLayout/cssClass.adoc | 6 --
.../pages/DomainObjectLayout/cssClassFa.adoc | 11 ++--
.../pages/DomainObjectLayout/cssClassUiEvent.adoc | 18 -----
.../pages/DomainObjectLayout/describedAs.adoc | 4 +-
.../pages/DomainObjectLayout/iconUiEvent.adoc | 15 -----
.../pages/DomainObjectLayout/layoutUiEvent.adoc | 22 ++-----
.../applib-ant/pages/DomainObjectLayout/named.adoc | 9 +--
.../applib-ant/pages/DomainObjectLayout/paged.adoc | 10 +--
.../pages/DomainObjectLayout/plural.adoc | 3 +-
.../pages/DomainObjectLayout/titleUiEvent.adoc | 16 +----
.../modules/applib-ant/pages/DomainService.adoc | 1 +
.../applib-ant/pages/DomainService/nature.adoc | 7 +-
.../applib-ant/pages/DomainService/objectType.adoc | 7 +-
.../applib-ant/pages/DomainServiceLayout.adoc | 1 +
.../main/adoc/modules/applib-ant/pages/Facets.adoc | 1 +
.../adoc/modules/applib-ant/pages/HomePage.adoc | 1 +
.../modules/applib-ant/pages/IsisSessionScope.adoc | 1 +
.../adoc/modules/applib-ant/pages/MemberOrder.adoc | 1 +
.../modules/applib-ant/pages/MemberOrder/name.adoc | 76 +++++++++++++++++++++-
.../applib-ant/pages/MemberOrder/sequence.adoc | 8 ++-
.../adoc/modules/applib-ant/pages/MinLength.adoc | 1 +
.../main/adoc/modules/applib-ant/pages/Mixin.adoc | 1 +
.../modules/applib-ant/pages/Mixin/method.adoc | 25 +++----
.../modules/applib-ant/pages/NotPersistent.adoc | 1 +
.../adoc/modules/applib-ant/pages/Nullable.adoc | 1 +
.../adoc/modules/applib-ant/pages/Parameter.adoc | 1 +
.../applib-ant/pages/Parameter/fileAccept.adoc | 23 +++----
.../applib-ant/pages/Parameter/maxLength.adoc | 7 +-
.../applib-ant/pages/Parameter/mustSatisfy.adoc | 46 ++++++++-----
.../applib-ant/pages/Parameter/optionality.adoc | 15 ++---
.../applib-ant/pages/Parameter/regexPattern.adoc | 20 +++---
.../modules/applib-ant/pages/ParameterLayout.adoc | 5 +-
.../applib-ant/pages/ParameterLayout/cssClass.adoc | 15 ++---
.../pages/ParameterLayout/describedAs.adoc | 17 ++---
.../pages/ParameterLayout/labelPosition.adoc | 18 +++--
.../pages/ParameterLayout/multiLine.adoc | 19 +++---
.../applib-ant/pages/ParameterLayout/named.adoc | 30 ++++-----
.../{renderedAsDayBefore.adoc => renderDay.adoc} | 29 ++++-----
.../pages/ParameterLayout/typicalLength.adoc | 9 ++-
.../adoc/modules/applib-ant/pages/Pattern.adoc | 1 +
.../applib-ant/pages/PersistenceCapable.adoc | 3 +-
.../adoc/modules/applib-ant/pages/PrimaryKey.adoc | 1 +
.../modules/applib-ant/pages/Programmatic.adoc | 1 +
.../adoc/modules/applib-ant/pages/Property.adoc | 1 +
.../applib-ant/pages/Property/domainEvent.adoc | 42 +++++++-----
.../modules/applib-ant/pages/Property/editing.adoc | 23 ++++---
.../applib-ant/pages/Property/fileAccept.adoc | 10 +--
.../modules/applib-ant/pages/Property/hidden.adoc | 23 ++++---
.../applib-ant/pages/Property/maxLength.adoc | 28 ++++----
.../pages/Property/mementoSerialization.adoc | 18 ++---
.../applib-ant/pages/Property/mustSatisfy.adoc | 28 +++++---
.../applib-ant/pages/Property/optionality.adoc | 66 ++++++++-----------
.../applib-ant/pages/Property/projecting.adoc | 12 ++--
.../applib-ant/pages/Property/publishing.adoc | 21 +++---
.../applib-ant/pages/Property/regexPattern.adoc | 14 ++--
.../modules/applib-ant/pages/PropertyLayout.adoc | 5 +-
.../applib-ant/pages/PropertyLayout/cssClass.adoc | 13 ++--
.../pages/PropertyLayout/describedAs.adoc | 11 +++-
.../applib-ant/pages/PropertyLayout/hidden.adoc | 21 +++---
.../pages/PropertyLayout/labelPosition.adoc | 27 ++++----
.../applib-ant/pages/PropertyLayout/multiLine.adoc | 16 +++--
.../applib-ant/pages/PropertyLayout/named.adoc | 17 ++---
.../applib-ant/pages/PropertyLayout/navigable.adoc | 23 +++++--
.../pages/PropertyLayout/promptStyle.adoc | 16 +++--
.../{renderedAsDayBefore.adoc => renderDay.adoc} | 33 +++++-----
.../pages/PropertyLayout/repainting.adoc | 11 +++-
.../pages/PropertyLayout/typicalLength.adoc | 11 +++-
.../main/adoc/modules/applib-ant/pages/Title.adoc | 1 +
.../adoc/modules/applib-ant/pages/ViewModel.adoc | 2 +-
.../applib-ant/pages/ViewModel/objectType.adoc | 8 +--
.../applib-ant/pages/XmlJavaTypeAdapter.adoc | 1 +
.../modules/applib-ant/pages/XmlRootElement.adoc | 1 +
.../applib-cm/pages/classes/value-types/Blob.adoc | 1 +
.../applib-cm/pages/classes/value-types/Clob.adoc | 1 +
.../applib-cm/pages/methods/prefixes/choices.adoc | 73 ++++++++++-----------
.../applib-cm/pages/methods/prefixes/default.adoc | 45 +++++++------
.../services/repository/RepositoryService.java | 3 +-
.../ROOT/pages/services/IsisJdoSupport.adoc | 69 ++------------------
.../adoc/modules/shiro/pages/about/run-as.adoc | 2 +-
.../ROOT/pages/features/blob-attachments.adoc | 2 +-
122 files changed, 844 insertions(+), 892 deletions(-)
diff --git a/api/adoc/userguide/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc b/api/adoc/userguide/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc
index 802ad88..ed727cf 100644
--- a/api/adoc/userguide/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc
+++ b/api/adoc/userguide/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc
@@ -32,7 +32,7 @@ import org.springframework.stereotype.Service;
import lombok.val;
@Service
-@Ordered(OrderPrecedence.HIGH) // <.>
+@Order(OrderPrecedence.HIGH) // <.>
public class RoutingServiceUsingBreadcrumbs
extends RoutingServiceDefault {
@Override
diff --git a/api/adoc/userguide/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc b/api/adoc/userguide/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc
index 57d3591..1ac4f2b 100644
--- a/api/adoc/userguide/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc
+++ b/api/adoc/userguide/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc
@@ -20,7 +20,7 @@ import org.springframework.stereotype.Service;
import org.springframework.core.Ordered;
@Service
-@Ordered(OrderPrecedence.HIGH) // <.>
+@Order(OrderPrecedence.HIGH) // <.>
public class MyLocaleProvider implements LocaleProvider {
@Override
public Locale getLocale() {
@@ -41,7 +41,7 @@ import org.springframework.stereotype.Service;
import org.springframework.core.Ordered;
@Service
-@Ordered(OrderPrecedence.HIGHEST) // <.>
+@Order(OrderPrecedence.HIGHEST) // <.>
public class MyLocaleProvider implements LocaleProvider {
@Inject List<LocaleProvider> localeProviders; // <.>
diff --git a/api/adoc/userguide/modules/fun/pages/drop-downs-and-defaults.adoc b/api/adoc/userguide/modules/fun/pages/drop-downs-and-defaults.adoc
index ab745f2..f5de6d1 100644
--- a/api/adoc/userguide/modules/fun/pages/drop-downs-and-defaults.adoc
+++ b/api/adoc/userguide/modules/fun/pages/drop-downs-and-defaults.adoc
@@ -151,7 +151,7 @@ with:
[source,java]
----
-@DomainService(nature=NatureOfService.VIEW_MENU_ONLY)
+@DomainService(nature = NatureOfService.VIEW)
public class Customers {
@Action(semantics=SemanticsOf.SAFE)
public List<Customer> findByReferenceOrName(@MinLength(3) String refOrName) {
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
index 417d55e..46a6dc4 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
@@ -1,3 +1,4 @@
+[#Action]
= `@Action`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
index be0dcfb..39bb9fb 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ActionLayout.adoc
@@ -1,3 +1,4 @@
+[#ActionLayout]
= `@ActionLayout`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc
index fa50629..f644766 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection.adoc
@@ -1,3 +1,4 @@
+[#Collection]
= `@Collection`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/editing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/editing.adoc
index d32b69f..ba783e3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/editing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/editing.adoc
@@ -21,25 +21,31 @@ Whether a collection is enabled or disabled depends upon these factors:
* whether the domain object has been configured as immutable through the xref:refguide:applib-ant:DomainObject.adoc#editing[`@DomainObject#editing()`] attribute
-* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:refguide:config:configuring-core.adoc[configuration property] `isis.objects.editing`.
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the
+xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.editing['isis.applib.annotation.domain-object.editing'] configuration property.
If set to `false`, then the object's collections (and properties) are *not* editable
* else, then the value of the `@Collection(editing=...)` attribute itself.
-* else, the result of invoking any supporting xref:refguide:applib-cm:rgcms.adoc#\_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:refguide:applib-cm:methods/prefixes.adoc#disable[`disable...()`] supporting methods
Thus, to make a collection read-only even if the object would otherwise be editable, use:
-
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@Collection(
editing=Editing.DISABLED,
editingDisabledReason="Use the add and remove actions to modify"
)
- public SortedSet<ToDoItem> getDependencies() { /* ... */ }
+ @Getter @Setter
+ private SortedSet<ToDoItem> dependencies = ...
+
}
----
@@ -48,7 +54,6 @@ public class ToDoItem {
To reiterate, it is _not_ possible to enable editing for a collection if editing has been disabled at the object-level.
====
-
== See also
This attribute can also be specified for:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc
index 786b863..100a7b7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/hidden.adoc
@@ -11,16 +11,21 @@ Collections can be hidden at the domain-level, indicating that they are not visi
[TIP]
====
It is also possible to use xref:refguide:applib-ant:CollectionLayout.adoc#hidden[`@CollectionLayout#hidden`] or using xref:userguide:fun:ui.adoc#object-layout[file-based layout] such that the collection can be hidden at the view layer.
-Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@Collection(where=Where.EVERYWHERE)
- public SortedSet<Address> getAddresses() { /* ... */ }
+ @Getter @Setter
+ private SortedSet<Address> addresses = ...
+
}
----
@@ -48,13 +53,6 @@ The other values of the `Where` enum have no meaning for a collection.
-[NOTE]
-====
-The xref:vw:ROOT:about.adoc[Wicket viewer] suppresses collections when displaying lists of objects.
-
-The xref:vro:ROOT:about.adoc[RestfulObjects viewer] by default suppress collections when rendering a domain object.
-====
-
== See also
This attribute can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc
index 914b8ae..09918db 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/mementoSerialization.adoc
@@ -12,11 +12,15 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@Collection(mementoSerialization=EXCLUDED)
- public SortedSet<Order> getPreviousOrders() {...}
- public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
- ...
+ @Getter @Setter
+ private SortedSet<Order> previousOrders = ...
+
}
----
@@ -26,6 +30,7 @@ Alternatively, if the collection is derived, then providing only a "getter" will
[source,java]
----
public class Customer {
+
public SortedSet<Order> getPreviousOrders() {...}
...
}
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/typeOf.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/typeOf.adoc
index 0fe94c4..c6ccf9c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/typeOf.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Collection/typeOf.adoc
@@ -7,15 +7,18 @@
The `typeOf` attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.
-
For example:
[source,java]
----
+import lombok.Getter;
+
public void Customer {
+
@Collection(typeOf=Order.class)
- public SortedSet getOutstandingOrders() { /* ... */ }
- ...
+ @Getter
+ private SortedSet outstandingOrders = ...
+
}
----
@@ -24,7 +27,6 @@ public void Customer {
In general we recommend that you use generics instead, eg `SortedSet<Order>`.
====
-
== See also
This attribute can also be specified for xref:refguide:applib-ant:Action.adoc#typeOf[actions].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
index b0a89b1..0734b42 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout.adoc
@@ -1,3 +1,4 @@
+[#CollectionLayout]
= `@CollectionLayout`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc
index 678781b..1b45b16 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/cssClass.adoc
@@ -7,31 +7,30 @@
The `cssClass` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection. xref:refguide:config:application-specific/application-css.adoc[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
-
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@CollectionLayout(
cssClass="x-important"
)
- public SortedSet<ToDoItem> getDependencies() { /* ... */ }
- ...
+ @Getter @Setter
+ private SortedSet<ToDoItem> dependencies = ...;
+
}
----
-
== Alternatives
-
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
== See also
-
This attribute can also be applied to:
* xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClass[domain objects]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc
index e788550..76b2528 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/defaultView.adoc
@@ -5,31 +5,31 @@
:page-partial:
-The xref:vw:ROOT:about.adoc[Wicket viewer] allows additional views to be configured to render collections of objects; at the time of writing these include the xref:vw:exceldownload:about.adoc[Excel Download], xref:vw:fullcalendar:about.adoc[Fullcalendar] and xref:vw:gmap3:about.adoc[Gmap3] extensions.
-If the objects to be rendered have the correct "shape", then the appropriate view will be made available.
-For example, objects with a date can be rendered using `calendar`; objects with locations can be rendered using `map`.
-
-The `defaultView` attribute is used to select which of these views should be used by default for a given collection.
+The `defaultView` attribute is used to select which of views should be used by default for a given collection.
+Without any hint the collection is shown collapsed (to save real estate and reduce load time).
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
+
public class BusRoute {
- @CollectionLayout(
- defaultView="map"
- )
- public SortedSet<BusStop> getStops() { /* ... */ }
- ...
+
+ @CollectionLayout( defaultView="table" ) // <.>
+ @Getter @Setter
+ private SortedSet<BusStop> stops = ...
+
}
----
+<.> renders the collection as a table view.
+
+The xref:vw:ROOT:about.adoc[Wicket viewer] allows additional views to be configured to render collections of objects, eg xref:vw:exceldownload:about.adoc[Excel Download] ("excel"), xref:vw:fullcalendar:about.adoc[Fullcalendar] ("fullcalendar") and xref:vw:gmap3:about.adoc[Gmap3] ("map") extensions.
+This attribute can be used to select any of these alternative views instead.
+
-[NOTE]
-====
-This attribute takes precedence over any value for the xref:refguide:applib-ant:CollectionLayout.adoc#render[`@CollectionLayout#render`] attribute.
-For example, if the
-`defaultView` attribute is defined to "table", then the table will be show even if `render` is set to `LAZILY`.
-====
== Alternatives
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc
index 41308ac..14bfe29 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/describedAs.adoc
@@ -5,27 +5,31 @@
:page-partial:
-The `describedAs` attribute is used to provide a short description of the collection to the user. In the xref:vw:ROOT:about.adoc[Wicket viewer] it is displayed as a 'tool tip'.
+The `describedAs` attribute is used to provide a short description of the collection to the user.
+In the xref:vw:ROOT:about.adoc[Wicket viewer] it is displayed as a 'tool tip'.
The `describedAs` attribute can also be specified for xref:refguide:applib-ant:PropertyLayout.adoc#describedAs[properties], xref:refguide:applib-ant:ActionLayout.adoc#describedAs[actions], xref:refguide:applib-ant:ParameterLayout.adoc#describedAs[parameters] and xref:refguide:applib-ant:DomainObjectLayout.adoc#describedAs[domain objects].
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@CollectionLayout(
- describedAs="Other todo items that must be completed before this one"
+ describedAs = "Todo items to be completed before this one"
)
- public SortedSet<ToDoItem> getDependencies() { /* ... */ }
- ...
+ @Getter @Setter
+ private SortedSet<ToDoItem> dependencies = ...
+
}
----
== Alternatives
-
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc
index fa94e6e..f744d38 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/hidden.adoc
@@ -7,27 +7,29 @@
The `hidden` attribute indicates where (in the UI) the collection should be hidden from the user.
-
-
[TIP]
====
It is also possible to use xref:refguide:applib-ant:Collection.adoc#hidden[`@Collection#hidden`] to hide an action at the domain layer.
-Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@CollectionLayout(
hidden=Where.EVERYWHERE
- public SortedSet<ToDoItem> getDependencies() { /* ... */ }
- ...
+ )
+ @Getter @Setter
+ private SortedSet<ToDoItem> dependencies = ...
+
}
----
-
The acceptable values for the `where` parameter are:
* `Where.EVERYWHERE` or `Where.ANYWHERE`
@@ -48,13 +50,10 @@ The collection should not be hidden.
The other values of the `Where` enum have no meaning for a collection.
-
== Alternatives
-
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
== See also
This attribute can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc
index 80125f2..9a456a7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/named.adoc
@@ -8,41 +8,39 @@
The `named` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code.
-
[TIP]
====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code.
+We recommend that you only use this attribute when the desired name cannot be used in Java source code.
Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
====
-
By default the name is HTML escaped.
To allow HTML markup, set the related `namedEscaped` attribute to `false`.
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
@CollectionLayout(
named="Todo items that are <i>dependencies</i> of this item",
namedEscaped=false
)
- public SortedSet<ToDoItem getDependencies() { /* ... */ }
- ...
+ @Getter @Setter
+ private SortedSet<ToDoItem> dependencies = ...
+
}
----
-
-
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
-
== See also
This attribute can also be specified for:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc
index d9f9a01..6544f41 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/paged.adoc
@@ -1,14 +1,12 @@
[#paged]
= `paged()`
-
+r
: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 [...]
:page-partial:
The `paged` attribute specifies the number of rows to display in a (parented) collection.
-
-
[WARNING]
====
The xref:vro:ROOT:about.adoc[RestfulObjects viewer] currently does not support paging.
@@ -17,27 +15,28 @@ The xref:vw:ROOT:about.adoc[Wicket viewer] _does_ support paging, but note that
We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
====
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Order {
+
@CollectionLayout(paged=15)
- public SortedSet<OrderLine> getDetails() {...}
+ @Getter @Setter
+ private SortedSet<OrderLine> details = ...
+
}
----
-
-It is also possible to specify a global default for the page size of standalone collections, using the xref:refguide:config:configuring-core.adoc[configuration property] `isis.viewer.paged.parented`.
-
-
+It is also possible to specify a global default for the page size of parented collections, using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.collection-layout.paged[`isis.applib.annotation.collection-layout.paged`] configuration property.
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
== See also
This attribute can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc
index f41b63c..80f30c3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/CollectionLayout/sortedBy.adoc
@@ -11,25 +11,29 @@ For example:
[source,java]
----
-public class ToDoItem implements Comparable<ToDoItem> { // <1>
- public static class DependenciesComparator // <2>
- implements Comparator<ToDoItem> {
+import lombok.Getter;
+import lombok.Setter;
+
+public class ToDoItem implements Comparable<ToDoItem> { // <.>
+
+ public static class DescriptionComparator // <.>
+ implements Comparator<ToDoItem> {
@Override
- public int compare(ToDoItem p, ToDoItem q) {
- return ORDERING_BY_DESCRIPTION // <3>
- .compound(Ordering.<ToDoItem>natural())
- .compare(p, q);
+ public int compare(ToDoItem o1, ToDoItem o2) {
+ return Comparator.comparing(ToDoItem::getDescription)
+ .compare(o1, o2);
}
}
- @CollectionLayout(sortedBy=DependenciesComparator.class) // <4>
- public SortedSet<ToDoItem> getDependencies() { /* ... */ }
- ...
+
+ @CollectionLayout(sortedBy=DependenciesComparator.class) // <.>
+ @Getter @Setter
+ private SortedSet<ToDoItem> dependencies = ...
+
}
----
-<1> the class has a natural ordering (implementation not shown)
-<2> declaration of the comparator class
-<3> ordering defined as being by the object's `description` property (not shown), and then by the natural ordering of the class
-<4> specify the comparator to use
+<.> the class has a natural ordering (implementation not shown)
+<.> declaration of an alternative comparator class, using the object's `description` property
+<.> ordering of the collection defined as being by this comparator
When the `dependencies` collection is rendered, the elements are sorted by the `description` property first:
@@ -41,10 +45,6 @@ Note that this screenshot shows an earlier version of the xref:vw:ROOT:about.ado
====
-Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.
-
-
-
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc
index 79374b9..043a96c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Column.adoc
@@ -1,3 +1,4 @@
+[#javax-jdo-annotation-Column]
= `@Column` (`javax.jdo`)
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Digits.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Digits.adoc
index 420f38e..6703c3c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Digits.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Digits.adoc
@@ -1,3 +1,4 @@
+[#javax-validation-constraints-Digits]
= `@Digits` (`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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc
index a03503a..804039b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Discriminator.adoc
@@ -1,3 +1,4 @@
+[#javax-jdo-annotation-Discrimnator]
= `@Discriminator` (`javax.jdo`)
: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 [...]
@@ -25,7 +26,7 @@ This can appear in several contexts, including:
(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
-* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (in general and in particular if xref:vw:ROOT:features.adoc#hints-and-copy-url[copying URLs])
+* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer]
* in XML snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`]
== Examples
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc
index 6441fef..e0806ed 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject.adoc
@@ -1,3 +1,4 @@
+[#DomainObject]
= `@DomainObject`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/actionDomainEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/actionDomainEvent.adoc
index 6460c7d..3653d79 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/actionDomainEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/actionDomainEvent.adoc
@@ -6,8 +6,8 @@
Whenever an action of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
-Using xref:refguide:applib-ant:Action.adoc#domainEvent[`@Action#domainEvent`], the actual domain event class fired can be customised.
-the `@DomainObject#actionDomainEvent` attribute allows a common event domain class to be fired for all of the actions of the domain object.
+The `@DomainObject#actionDomainEvent` attribute allows a common event domain class to be fired for all of the actions of the domain object.
+This can be overridden for any given action using xref:refguide:applib-ant:Action.adoc#domainEvent[`@Action#domainEvent`].
For example:
@@ -17,9 +17,10 @@ For example:
actionDomainEvent=ToDoItem.ActionDomainEventDefault.class
)
public class ToDoItem {
- public static class ActionDomainEventDefault
- extends org.apache.isis.applib.services.eventbus.ActionDomainEvent<Object> { }
- ...
+
+ public static class ActionDomainEventDefault extends
+ org.apache.isis.applib.events.domain.ActionDomainEvent<Object> { }
+ // ...
public void updateDescription(final String description) {
this.description = description;
@@ -28,10 +29,9 @@ public class ToDoItem {
}
----
+The specified class will also be used as the event for any mixin action contributed to the class.
-Interactions with the property contributed by this mixin will emit the domain event of the subject (`ToDoItem`).
-
-One small difference between the events emitted by a "regular" action and a contributed action is that the source of the event (as in `event#getSource()` will be different.
+Note though one small difference between the events emitted by a "regular" action and a contributed action is that the source of the event (as in `event#getSource()` will be different.
In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.
However, the domain object is available using `event#getMixedIn()`.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/auditing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/auditing.adoc
index c980941..cb2e9cb 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/auditing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/auditing.adoc
@@ -7,7 +7,7 @@
The `auditing` attribute indicates that if the object is modified, then each of its changed properties should be submitted to the registered xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s).
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:configuring-core.adoc[configuration property] `isis.services.audit.objects` is used to determine the whether the action is audited:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.auditing[`isis.applib.annotation.domain-object.auditing`] configuration property is used to determine the whether the action is audited:
* `all` +
+
@@ -26,13 +26,13 @@ For example:
[source,java]
----
@DomainObject(
- auditing=Auditing.ENABLED // <1>
+ auditing=Auditing.ENABLED // <.>
)
public class Customer {
...
}
----
-<1> because set to enabled, will be audited irrespective of the configured value.
+<.> because set to enabled, will be audited irrespective of the configured value.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/autoCompleteRepository.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/autoCompleteRepository.adoc
index eb2c000..d17fcc1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/autoCompleteRepository.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/autoCompleteRepository.adoc
@@ -11,13 +11,11 @@ The `autoCompleteRepository` attribute nominates a single method on a domain ser
For example, this might search for a customer by their name or number.
Or it could search for a country based on its ISO-3 code or user-friendly name.
-
[TIP]
====
If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:refguide:applib-cm:methods.adoc#autoComplete[`autoComplete...()`] supporting method instead.
====
-
For example:
[source,java]
@@ -42,13 +40,11 @@ public class CustomerRepository {
----
<1> is assumed to be called "autoComplete", and accepts a single string
-
-
[#autoCompleteAction]
== `autoCompleteAction()`
-As noted above, by default the method invoked on the repository is assumed to be called "autoComplete". The optional `autoCompleteAction` attribute allows the method on the repository to be overridden.
-
+As noted above, by default the method invoked on the repository is assumed to be called "autoComplete".
+The optional `autoCompleteAction` attribute allows the method on the repository to be overridden.
For example:
@@ -67,23 +63,25 @@ where in this case `findByName` might be an existing action already defined:
[source,java]
----
-@DomainService(natureOfService=VIEW_MENU_ONLY)
+@DomainService(nature = NatureOfService.VIEW)
public class Customers {
+
@Action(semantics=SemanticsOf.SAFE)
public List<Customer> findByName(
- @MinLength(3) // <1>
+ @MinLength(3) // <.>
@ParameterLayout(named="name")
String name);
...
}
----
-<1> end-user must enter minimum number of characters to trigger the query
+<.> end-user must enter minimum number of characters to trigger the query
-The autocomplete action can also be a regular method, annotated using xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`]:
+The autocomplete "action" can also be a regular method, annotated using xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`].
+That is, it does not need to be part of the metamodel:
[source,java]
----
-@DomainService(natureOfService=VIEW_MENU_ONLY)
+@DomainService(nature = NatureOfService.VIEW)
public class Customers {
@Programmatic
public List<Customer> findByName(
@@ -93,11 +91,3 @@ public class Customers {
}
----
-
-[IMPORTANT]
-====
-The method specified must be an action, that is, part of the Isis metamodel.
-Said another way: it must not be annotated with xref:refguide:applib-ant:Programmatic.adoc[`@Programmatic`].
-However, it *can* be hidden or placed on a domain service with xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `DOMAIN`, such that the action would not be rendered otherwise in the UI.
-Also, the action cannot be xref:refguide:applib-ant:Action.adoc#restrictTo[restricted to] prototyping only.
-====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/bounding.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/bounding.adoc
index 3fb4803..f2522c3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/bounding.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/bounding.adoc
@@ -3,7 +3,7 @@
: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 [...]
:page-partial:
-
+r
Some domain classes are immutable to the user, and moreover have only a fixed number of instances.
@@ -13,21 +13,19 @@ Typical examples could include categories, countries, states, and tax or interes
Where the number of instances is relatively small, ie bounded, then the `bounding` attribute can be used as a hint.
For such domain objects the framework will automatically allow instances to be selected; xref:vw:ROOT:about.adoc[Wicket viewer] displays these as a drop-down list.
-
For example:
[source,java]
----
@DomainObject(
bounding=Bounding.BOUNDED,
- editing=Editing.DISABLED // <1>
+ editing=Editing.DISABLED // <.>
)
public class Currency {
...
}
----
-<1> This attribute is commonly combined with `editing=DISABLED` to enforce the fact that reference data is immutable
-
+<.> This attribute is commonly combined with `editing=DISABLED` to enforce the fact that reference data is immutable
[TIP]
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/collectionDomainEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/collectionDomainEvent.adoc
index ed859db..7b5f342 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/collectionDomainEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/collectionDomainEvent.adoc
@@ -6,23 +6,26 @@
Whenever a collection of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
-Using xref:refguide:applib-ant:Collection.adoc#domainEvent[`@Collection#domainEvent()`], the actual domain event class fired can be customised.
the `@DomainObject#collectionDomainEvent` attribute allows a common event domain class to be fired for all of the collections of the domain object.
+This can be overridden for any given collection using xref:refguide:applib-ant:Collection.adoc#domainEvent[`@Collection#domainEvent()`].
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
@DomainObject(
collectionDomainEvent=ToDoItem.CollectionDomainEventDefault.class
)
public class ToDoItem {
- public static class CollectionDomainEventDefault
- extends org.apache.isis.applib.events.domain.CollectionDomainEvent<Object> { }
+ public static class CollectionDomainEventDefault extends
+ org.apache.isis.applib.events.domain.CollectionDomainEvent<Object> { }
...
@Getter @Setter
- private Set<Category> categories = Sets.newTreeSet();
+ private Set<Category> categories = new TreeSet<>();
}
----
@@ -31,16 +34,17 @@ For example:
[source,java]
----
-@Mixin(method="coll")
-public class ToDoItem_related {
- private final ToDoItem todoItem;
- // constructor omitted
+public class ToDoItem {
- @Action(semantics = SemanticsOf.SAFE)
- @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
@Collection
@CollectionLayout(defaultView = "table")
- public List<ToDoItem> coll() { /* ... */ }
+ public class related {
+
+ public List<ToDoItem> coll() {
+ // ...
+ }
+ }
+
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/createdLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/createdLifecycleEvent.adoc
index 7523353..af82ecd 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/createdLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/createdLifecycleEvent.adoc
@@ -17,7 +17,6 @@ It's possible to instantiate objects without firing this lifecycle; just instant
xref:refguide:applib-svc:ServiceRegistry.adoc[`injectServicesInto(...)`] to manually inject any required domain services.
====
-
By default the event raised is `ObjectCreatedEvent.Default`.
For example:
@@ -48,9 +47,6 @@ public class ToDoItem {
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -89,9 +85,6 @@ public class SomeSubscriber {
}
----
-
-
-
== Default, Doop and Noop events
If the `createdLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectCreatedEvent.Default`), then the framework will, by default, post an event.
@@ -99,8 +92,7 @@ If the `createdLifecycleEvent` attribute is not explicitly specified (is left as
If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.createdLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `createdLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectCreatedEvent.Doop` as such a subclass, so setting the `createdLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ObjectCreatedEvent.Doop` as such a subclass, so setting the `createdLifecycleEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
And, conversely, the framework also provides `ObjectCreatedEvent.Noop`; if `createdLifecycleEvent` attribute is set to this class, then no event will be posted.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc
index 6391c4f..8dae10b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc
@@ -4,20 +4,16 @@
: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 [...]
:page-partial:
-
-WARNING: TODO - v2 - not yet reviewed/updated.
-
The `editing` attribute determines whether a domain object's properties and collections are not editable (are read-only).
-The default is `AS_CONFIGURED`, meaning that the xref:refguide:config:configuring-core.adoc[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
+The default is `AS_CONFIGURED`, meaning that the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.editing[`isis.applib.annotation.domain-object.editing`]
+configuration property is used to determine the whether the object is modifiable:
* `true` +
-+
-the object's properties and collections are modifiable.
++ the object's properties and collections are modifiable.
* `false` +
-+
-the object's properties and collections are read-only, ie _not_ modifiable.
++ the object's properties and collections are read-only, ie _not_ modifiable.
If there is no configuration property in `application.properties` then object are assumed to be modifiable.
@@ -33,9 +29,6 @@ isis.applib.annotation.domain-object.editing=false
We recommend this setting; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
====
-
-
-
This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
For example:
@@ -51,11 +44,3 @@ public class Country {
}
----
-[TIP]
-====
-Another interesting example of immutable reference data is to define an entity to represent individual dates; after all, for a system with an expected lifetime of 20 years that equates to only 7,300 days, a comparatively tiny number of rows to hold in a database.
-====
-
-
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/loadedLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/loadedLifecycleEvent.adoc
index 127d57c..48d344e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/loadedLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/loadedLifecycleEvent.adoc
@@ -10,7 +10,8 @@ Whenever a persistent domain object is loaded from the database, a "loaded" life
Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can use the event to obtain a reference to the domain object just loaded.
The subscriber could then, for example, update or default values on the object (eg to support on-the-fly migration scenarios).
-By default the event raised is `ObjectLoadedEvent.Default`. For example:
+By default the event raised is `ObjectLoadedEvent.Default`.
+For example:
[source,java]
----
@@ -31,17 +32,14 @@ For example:
loadedLifecycleEvent=ToDoItem.LoadedEvent.class
)
public class ToDoItem {
- public static class LoadedEvent
- extends org.apache.isis.applib.events.lifecycle.ObjectLoadedEvent<ToDoItem> { }
+ public static class LoadedEvent extends
+ org.apache.isis.applib.events.lifecycle.ObjectLoadedEvent<ToDoItem> { }
...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -80,11 +78,6 @@ public class SomeSubscriber {
}
----
-
-
-
-
-
== Default, Doop and Noop events
If the `loadedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectLoadedEvent.Default`), then the framework will, by default, post an event.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/mixinMethod.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/mixinMethod.adoc
index 4ee78b5..6b2c491 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/mixinMethod.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/mixinMethod.adoc
@@ -15,19 +15,30 @@ For example:
@DomainObject
public class Customer {
- @DomainObject(nature=Nature.MIXIN, mixinMethod="execute")
- public static class placeOrder {
-
- Customer customer;
- public placeOrder(Customer customer) { this.customer = customer; }
-
- public Customer execute(Product p, int quantity) { /* ... */ }
- public String disableExecute() { /* ... */ }
- public String validate0Execute() { /* ... */ }
+ @DomainObject(
+ nature=Nature.MIXIN, // <.>
+ mixinMethod="execute" // <.>
+ )
+ public class placeOrder {
+
+ public Customer execute(Product p, int quantity) { // <.>
+ // ...
+ }
+ public String disableExecute() {
+ // ...
+ }
+ public String validate0Execute() {
+ // ...
+ }
}
- ...
+
)
----
+<.> This is a mixin. +
+Alternatively, could have used xref:refguide:applib-ant:Mixin.adoc[`@Mixin`].
+<.> This mixin is using a non-standard method. +
+Alternatively, could have used xref:refguide:applib-ant:Mixin.adoc#method[`@Mixin#method()`].
+<.> Same name as the specified mixinMethod.
This allows all mixins to follow a similar convention, with the name of the mixin inferred entirely from its type ("placeOrder").
@@ -35,6 +46,6 @@ When invoked programmatically, the code reads:
[source,java]
----
-mixin(Customer.placeOrder.class, someCustomer).execute(someProduct, 3);
+someCustomer.new placeOrder().execute(someProduct, 3);
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc
index 84d0ea6..6ddd249 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/nature.adoc
@@ -21,15 +21,15 @@ public class PieChartAnalysis {
Specifically, the nature must be one of:
-* `NOT_SPECIFIED,` +
+* `NOT_SPECIFIED,`
+
(the default); specifies no paricular semantics for the domain class.
-* `JDO_ENTITY` +
+* `JDO_ENTITY`
+
indicates that the domain object is an entity whose persistence is managed internally by Apache Isis, using the JDO/DataNucleus objectstore.
-* `EXTERNAL_ENTITY` +
+* `EXTERNAL_ENTITY`
+
indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system.
For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP.
@@ -37,28 +37,25 @@ For example, the domain object may hold just the URI to a RESTful resource of so
The identity of an external entity is determined solely by the state of entity's properties.
The framework will automatically recreate the domain object each time it is interacted with.
-* `INMEMORY_ENTITY` +
+* `INMEMORY_ENTITY`
+
indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure.
+
The identity of an inmemory entity is determined solely by the state of entity's properties.
The framework will automatically recreate the domain object each time it is interacted with.
-* `MIXIN` +
+* `MIXIN`
+
indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
+
Equivalent to annotating with xref:refguide:applib-ant:Mixin.adoc[`@Mixin`].
For further discussion on using mixins, see xref:userguide:fun:overview.adoc#mixins[mixins] in the user guide.
-
-* `VIEW_MODEL` +
+* `VIEW_MODEL`
+
indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.
-As such the domain object's class cannot be annotated with xref:refguide:applib-ant:ViewModel.adoc[`@ViewModel`] or implement the xref:refguide:applib-cm:classes/super.adoc#ViewModel[`ViewModel`] interface.
-
[NOTE]
====
@@ -76,5 +73,3 @@ On the other hand, view models defined in this way do have some limitations; see
These limitations do _not_ apply to xref:userguide:fun:view-models.adoc#jaxb[JAXB] view models.
If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
====
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/objectType.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/objectType.adoc
index 2e4f10f..64714c4 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/objectType.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/objectType.adoc
@@ -11,14 +11,12 @@ This value is used internally to generate a string representation of an objects
This can appear in several contexts, including:
* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
+(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
-* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (in general and in particular if xref:vw:ROOT:features.adoc#hints-and-copy-url[copying URLs])
+* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer]
* in XML snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`]
-
-
== Examples
For example:
@@ -33,7 +31,6 @@ public class Order {
}
----
-
== Precedence
The rules of precedence are:
@@ -47,7 +44,6 @@ If only `schema` is defined, then the value is "`schema.className`".
4. Fully qualified class name of the entity.
-
[TIP]
====
This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistedLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistedLifecycleEvent.adoc
index 6d91d37..4070a7a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistedLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistedLifecycleEvent.adoc
@@ -37,17 +37,16 @@ For example:
persistedLifecycleEvent=ToDoItem.PersistedEvent.class
)
public class ToDoItem {
- public static class PersistedEvent
- extends org.apache.isis.applib.events.lifecycle.ObjectPersistedEvent<ToDoItem> { }
- ...
+
+ public static class PersistedEvent extends
+ org.apache.isis.applib.events.lifecycle.ObjectPersistedEvent<ToDoItem> { }
+
+ // ...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -86,12 +85,6 @@ public class SomeSubscriber {
}
----
-
-
-
-
-
-
== Default, Doop and Noop events
If the `persistedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistedEvent.Default`), then the framework will, by default, post an event.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistingLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistingLifecycleEvent.adoc
index 75335b8..68ab73a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistingLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/persistingLifecycleEvent.adoc
@@ -39,17 +39,16 @@ For example:
persistingLifecycleEvent=ToDoItem.PersistingEvent.class
)
public class ToDoItem {
- public static class PersistingEvent
- extends org.apache.isis.applib.events.lifecycle.ObjectPersistingEvent<ToDoItem> { }
- ...
+
+ public static class PersistingEvent extends
+ org.apache.isis.applib.events.lifecycle.ObjectPersistingEvent<ToDoItem> { }
+
+ // ...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -83,16 +82,11 @@ import org.springframework.stereotype.Service;
public class SomeSubscriber {
@EventListener(ToDoItem.ObjectPersistingEvent.class)
public void on(ToDoItem.ObjectPersistingEvent ev) {
- ...
+ // ...
}
}
----
-
-
-
-
-
== Default, Doop and Noop events
If the `persistingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistingEvent.Default`), then the framework will, by default, post an event.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/propertyDomainEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/propertyDomainEvent.adoc
index 73858c1..13a3216 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/propertyDomainEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/propertyDomainEvent.adoc
@@ -6,8 +6,8 @@
Whenever a property of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
-Using xref:refguide:applib-ant:Property.adoc#domainEvent[`@Property#domainEvent()`], the actual domain event class fired can be customised.
-the `@DomainObject#propertyDomainEvent` attribute allows a common event domain class to be fired for all of the properties of the domain object.
+The `@DomainObject#propertyDomainEvent` attribute allows a common event domain class to be fired for all of the properties of the domain object.
+This can be overridden for any given property using xref:refguide:applib-ant:Property.adoc#domainEvent[`@Property#domainEvent()`].
For example:
@@ -26,7 +26,6 @@ public class ToDoItem {
}
----
-
If there is a mixin for the domain object, then this will also honour the domain event.
For example:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc
index 93cfa06..789ed71 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc
@@ -29,13 +29,13 @@ For example:
[source,java]
----
@DomainObject(
- publishing=Publishing.ENABLED // <1>
+ publishing=Publishing.ENABLED // <.>
)
public class InterestRate {
...
}
----
-<1> because set to enabled, will be published irrespective of the configured value.
+<.> because set to enabled, will be published irrespective of the configured value.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/removingLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/removingLifecycleEvent.adoc
index 1ec06a3..5d6daaa 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/removingLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/removingLifecycleEvent.adoc
@@ -1,6 +1,6 @@
[#removingLifecycleEvent]
= `removingLifecycleEvent()`
-
+r
: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 [...]
:page-partial:
@@ -39,17 +39,16 @@ For example:
removingLifecycleEvent=ToDoItem.RemovingEvent.class
)
public class ToDoItem {
- public static class RemovingEvent
- extends org.apache.isis.applib.events.lifecycle.ObjectRemovingEvent<ToDoItem> { }
- ...
+
+ public static class RemovingEvent extends
+ org.apache.isis.applib.events.lifecycle.ObjectRemovingEvent<ToDoItem> { }
+
+ // ...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -88,12 +87,6 @@ public class SomeSubscriber {
}
----
-
-
-
-
-
-
== Default, Doop and Noop events
If the `removingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectRemovingEvent.Default`), then the framework will, by default, post an event.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatedLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatedLifecycleEvent.adoc
index eac4922..e11e84e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatedLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatedLifecycleEvent.adoc
@@ -36,17 +36,16 @@ For example:
updatedLifecycleEvent=ToDoItem.UpdatedEvent.class
)
public class ToDoItem {
- public static class UpdatedEvent
- extends org.apache.isis.applib.events.lifecycle.ObjectUpdatedEvent<ToDoItem> { }
- ...
+
+ public static class UpdatedEvent extends
+ org.apache.isis.applib.events.lifecycle.ObjectUpdatedEvent<ToDoItem> { }
+
+ // ...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -85,13 +84,6 @@ public class SomeSubscriber {
}
----
-
-
-
-
-
-
-
== Default, Doop and Noop events
If the `updatedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatedEvent.Default`), then the framework will, by default, post an event.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatingLifecycleEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatingLifecycleEvent.adoc
index 5fd9d84..a5a4d85 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatingLifecycleEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/updatingLifecycleEvent.adoc
@@ -40,17 +40,16 @@ For example:
updatingLifecycleEvent=ToDoItem.UpdatingEvent.class
)
public class ToDoItem {
- public static class UpdatingEvent
- extends org.apache.isis.applib.events.lifecycle.ObjectUpdatingEvent<ToDoItem> { }
- ...
+
+ public static class UpdatingEvent extends
+ org.apache.isis.applib.events.lifecycle.ObjectUpdatingEvent<ToDoItem> { }
+
+ // ...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -89,14 +88,9 @@ public class SomeSubscriber {
}
----
-
-
-
-
== Default, Doop and Noop events
-If the `updatingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatingEvent.Default`),
-then the framework will, by default, post an event.
+If the `updatingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatingEvent.Default`), then the framework will, by default, post an event.
If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatingLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
index d2f7e08..619e70d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout.adoc
@@ -1,3 +1,4 @@
+[#DomainObjectLayout]
= `@DomainObjectLayout`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/bookmarking.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/bookmarking.adoc
index f81687e..c217883 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/bookmarking.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/bookmarking.adoc
@@ -7,9 +7,9 @@
The `bookmarking` attribute indicates that an entity is automatically bookmarked.
-This attribute is also supported for xref:refguide:applib-ant:Action.adoc#bookmarking[domain objects].
+This attribute is also supported for xref:refguide:applib-ant:ActionLayout.adoc#bookmarking[domain objects].
-(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
+In the xref:vw:ROOT:about.adoc[Wicket Viewer], a link to a bookmarked object is shown in the bookmarks panel:
image::reference-annotations/DomainObjectLayout/bookmarking.png[width="720px",link="{imagesdir}/reference-annotations/DomainObjectLayout/bookmarking.png"]
@@ -30,19 +30,16 @@ public class ToDoItem ... {
indicates that the `ToDoItem` class is bookmarkable:
-
It is also possible to nest bookmarkable entities.
-For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
+For example:
image::reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px",link="{imagesdir}/reference-annotations/DomainObjectLayout/bookmarking-nested.png"]
-
[NOTE]
====
Note that this screenshot shows an earlier version of the xref:vw:ROOT:about.adoc[Wicket viewer] UI (specifically, pre 1.8.0).
====
-
For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark, but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark _but only if_ its parent `Property` has already been bookmarked.
This is accomplished with the following annotations:
@@ -50,7 +47,9 @@ This is accomplished with the following annotations:
[source,java]
----
@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
-public class Property { /* ... */ }
+public class Property {
+ // ...
+}
----
and
@@ -58,10 +57,12 @@ and
[source,java]
----
@DomainObject(bookmarking=BookmarkPolicy.AS_CHILD)
-public abstract class Unit { /* ... */ }
+public abstract class Unit {
+ // ...
+}
----
-The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting `Lease` > `LeaseItem` > `LeaseTerm` (3 levels deep).
+The nesting can be done to any level.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc
index f382b2c..36a37d7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClass.adoc
@@ -9,7 +9,6 @@
The `cssClass` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.
xref:refguide:config:application-specific/application-css.adoc[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
-
For example:
[source,java]
@@ -21,16 +20,11 @@ For example:
public class ToDoItem { /* ... */ }
----
-
-
-
[NOTE]
====
The similar xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
====
-
-
== See also
This attribute can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc
index 0b9961a..1b78534 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassFa.adoc
@@ -1,6 +1,6 @@
[#cssClassFa]
= `cssClassFa()`
-
+r
: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 [...]
:page-partial:
@@ -10,8 +10,6 @@ The `cssClassFa` attribute is used to specify the name of a link:http://fortawes
If necessary the icon specified can be overridden by a particular object instance using the xref:refguide:applib-cm:methods.adoc#iconName[`iconName()`] method.
-
-
For example:
[source,java]
@@ -19,23 +17,22 @@ For example:
@DomainObjectLayout(
cssClassFa="fa-check-circle"
)
-public class ToDoItem { /* ... */ }
+public class ToDoItem {
+ // ...
+}
----
There can be multiple "fa-" classes, eg to mirror or rotate the icon.
There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list.
The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
-
The related `cssClassFaPosition` attribute is currently unused for domain objects; the icon is always rendered to the left.
-
[TIP]
====
The similar xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
====
-
== See also
These attributes can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
index 3016d69..92afcc9 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
@@ -12,12 +12,6 @@ This is as an alternative to implementing xref:refguide:applib-cm:methods.adoc#c
Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
From this they can, if they wish, specify a CSS class for the domain object using the event's API.
-[NOTE]
-====
-The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:overview.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:userguide:fun:overview.adoc#mixins[mixin]s can be used to provide the behaviour.
-====
-
By default the event raised is `CssClassUiEvent.Default`.
For example:
@@ -48,9 +42,6 @@ public class ToDoItemDto {
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -91,10 +82,6 @@ public class SomeSubscriber {
The subscriber should then use `CssClassUiEvent#setCssClass(...)` to actually specify the CSS class to be used.
-
-
-
-
== Default, Doop and Noop events
If the `cssClassUiEvent` attribute is not explicitly specified (is left as its default value, `CssClassUiEvent.Default`), then the framework will, by default, post an event.
@@ -106,11 +93,6 @@ The framework provides `CssClassUiEvent.Doop` as such a subclass, so setting the
And, conversely, the framework also provides `CssClassUiEvent.Noop`; if `cssClassUiEvent` attribute is set to this class, then no event will be posted.
-
-
-
-
-
== Raising events programmatically
Normally events are only raised for interactions through the UI.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/describedAs.adoc
index 6348455..3ee9a5e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/describedAs.adoc
@@ -13,7 +13,9 @@ For example:
[source,java]
----
@DomainObjectLayout(
- describedAs="A customer who may have originally become known to us via the marketing system or who may have contacted us directly."
+ describedAs = "A customer who may have originally become"
+ + " known to us via the marketing system or who may"
+ + " have contacted us directly."
)
public class ProspectiveSale {
...
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc
index 02ee65f..a73e9ab 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/iconUiEvent.adoc
@@ -12,13 +12,6 @@ This is as an alternative to implementing xref:refguide:applib-cm:methods.adoc#i
Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
From this they can, if they wish, specify an icon name for the domain object using the event's API.
-
-[NOTE]
-====
-The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:overview.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:userguide:fun:overview.adoc#mixins[mixin]s can be used to provide the behaviour.
-====
-
By default the event raised is `IconUiEvent.Default`.
For example:
@@ -49,9 +42,6 @@ public class ToDoItemDto {
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -92,9 +82,6 @@ public class SomeSubscriber {
The subscriber should then use `IconUiEvent#setIconName(...)` to actually specify the icon name to be used.
-
-
-
== Default, Doop and Noop events
If the `iconUiEvent` attribute is not explicitly specified (is left as its default value, `IconUiEvent.Default`), then the framework will, by default, post an event.
@@ -106,8 +93,6 @@ The framework provides `IconUiEvent.Doop` as such a subclass, so setting the `ic
And, conversely, the framework also provides `IconUiEvent.Noop`; if `iconUiEvent` attribute is set to this class, then no event will be posted.
-
-
== Raising events programmatically
Normally events are only raised for interactions through the UI.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc
index e04acb6..05856da 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/layoutUiEvent.adoc
@@ -19,7 +19,7 @@ For example:
----
@DomainObjectLayout
public class ToDoItemDto {
- ...
+ // ...
}
----
@@ -34,17 +34,16 @@ For example:
iconUiEvent=ToDoItemDto.LayoutUiEvent.class
)
public class ToDoItemDto {
- public static class LayoutUiEvent
- extends org.apache.isis.applib.events.ui.LayoutUiEvent<ToDoItemDto> { }
- ...
+
+ public static class LayoutUiEvent extends
+ org.apache.isis.applib.events.ui.LayoutUiEvent<ToDoItemDto> { }
+
+ // ...
}
----
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -85,10 +84,6 @@ public class SomeSubscriber {
The subscriber should then use `LayoutUiEvent#setLayout(...)` to actually specify the CSS class to be used.
-
-
-
-
== Default, Doop and Noop events
If the `layoutUiEvent` attribute is not explicitly specified (is left as its default value, `LayoutUiEvent.Default`), then the framework will, by default, post an event.
@@ -100,11 +95,6 @@ The framework provides `LayoutUiEvent.Doop` as such a subclass, so setting the `
And, conversely, the framework also provides `LayoutUiEvent.Noop`; if `layoutUiEvent` attribute is set to this class, then no event will be posted.
-
-
-
-
-
== Raising events programmatically
Normally events are only raised for interactions through the UI.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/named.adoc
index a063140..afa75ec 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/named.adoc
@@ -7,15 +7,12 @@
The `named` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code.
-
-
[TIP]
====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code.
+We recommend that you only use this attribute when the desired name cannot be used in Java source code.
Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
====
-
For example:
[source,java]
@@ -24,19 +21,17 @@ For example:
named="Customer"
)
public class CustomerImpl implements Customer{
- ...
+ // ...
}
----
It's also possible to specify a xref:refguide:applib-ant:DomainObjectLayout.adoc#plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
-
[TIP]
====
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
====
-
== See also
The attribute can also be specified for:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/paged.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/paged.adoc
index 4e03e8d..35cc730 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/paged.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/paged.adoc
@@ -8,8 +8,6 @@
The `paged` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation.
-
-
[WARNING]
====
The xref:vro:ROOT:about.adoc[RestfulObjects viewer] currently does not support paging.
@@ -18,21 +16,17 @@ The xref:vw:ROOT:about.adoc[Wicket viewer] _does_ support paging, but note that
We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
====
-
For example:
[source,java]
----
@DomainObjectLayout(paged=15)
public class Order {
- ...
+ // ...
}
----
-
-It is also possible to specify a global default for the page size of standalone collections, using the xref:refguide:config:configuring-core.adoc[configuration property] `isis.viewer.paged.standalone`.
-
-
+It is also possible to specify a global default for the page size of standalone collections, using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object-layout.paged[`isis.applib.annotation.domain-object-layout.paged`] configuration property.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/plural.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/plural.adoc
index 79ada8f..1b59f84 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/plural.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/plural.adoc
@@ -5,7 +5,6 @@
:page-partial:
-
When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
The `plural` attribute allows the plural form of the class name to be specified explicitly.
@@ -16,7 +15,7 @@ For example:
----
@DomainObjectLayout(plural="Children")
public class Child {
- ...
+ // ...
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc
index ab2913b..c4dde7c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObjectLayout/titleUiEvent.adoc
@@ -9,16 +9,9 @@ Whenever a domain object is to be rendered, the framework fires off a title UI e
This is as an alternative to implementing xref:refguide:applib-cm:methods.adoc#title[`title()`] reserved method, or using the xref:refguide:applib-ant:Title.adoc[`@Title`] annotation, within the class itself.
(If either `title()` or `@Title` are present, then they will take precedence).
-Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can
-use obtain a reference to the domain object from the event.
+Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can use obtain a reference to the domain object from the event.
From this they can, if they wish, specify a title for the domain object using the event's API.
-[NOTE]
-====
-The feature was originally introduced so that xref:refguide:applib-ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:userguide:fun:overview.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:userguide:fun:overview.adoc#mixins[mixin]s can be used to provide the behaviour.
-====
-
By default the event raised is `TitleUiEvent.Default`.
For example:
@@ -49,9 +42,6 @@ public class ToDoItemDto {
The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -92,9 +82,6 @@ public class SomeSubscriber {
The subscriber should then use either `TitleUiEvent#setTranslatableTitle(...)` or `TitleUiEvent#setTitle(...)` to actually specify the title to be used.
-
-
-
== Default, Doop and Noop events
If the `titleUiEvent` attribute is not explicitly specified (is left as its default value, `TitleUiEvent.Default`), then the framework will, by default, post an event.
@@ -106,7 +93,6 @@ The framework provides `TitleUiEvent.Doop` as such a subclass, so setting the `t
And, conversely, the framework also provides `TitleUiEvent.Noop`; if `titleUiEvent` attribute is set to this class, thn no event will be posted.
-
== Raising events programmatically
Normally events are only raised for interactions through the UI.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc
index 8b0e0d0..8cce52f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService.adoc
@@ -1,3 +1,4 @@
+[#DomainService]
= `@DomainService`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc
index 98900ec..57c24fc 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/nature.adoc
@@ -5,8 +5,6 @@
:page-partial:
-By default, a domain service's actions will be rendered in the application menu bar _and_ be contributed _and_ appear in the REST API _and_ (of course) be available to invoke programmatically wherever that domain service is injected.
-This is great for initial prototyping, but later on you may prefer to add a little more structure.
This is the purpose of the `nature` attribute: to indicates the intent of (all of) the actions defined within the domain service.
The values of the enum are:
@@ -19,10 +17,9 @@ The default; the service's actions appear on menu bars, can be contributed, appe
+
The service's actions are intended only to be listed in the REST API exposed by the xref:vro:ROOT:about.adoc[RestfulObjects viewer].
-
The actual class name of the domain service is only rendered for the `VIEW` natures.
-For other services, just use Spring's `@Service`, `@Repository` or `@Component`.
+For other services (whose actions should not be part of the metamodel and should not appear in the UI), just use Spring's `@Service`, `@Repository` or `@Component` annotations.
Another example:
@@ -36,8 +33,6 @@ public class LoanRepository {
}
----
-
-
A final example:
[source,java]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc
index 785a147..9107075 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainService/objectType.adoc
@@ -11,13 +11,11 @@ This value is used internally to generate a string representation of an service
This can appear in several contexts, including:
* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
+(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (specifically, for bookmarked actions)
-
-
== Example
For example:
@@ -32,8 +30,6 @@ public class OrderMenu {
}
----
-
-
== Precedence
The rules of precedence are:
@@ -42,7 +38,6 @@ The rules of precedence are:
2. xref:refguide:applib-cm:methods.adoc#getId[`getId()`]
3. The fully qualified class name.
-
[TIP]
====
This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain services.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
index b7f3e69..55deaa1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainServiceLayout.adoc
@@ -1,3 +1,4 @@
+[#DomainServiceLayout]
= `@DomainServiceLayout`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc
index bd3fea8..ee6e770 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Facets.adoc
@@ -1,3 +1,4 @@
+[#Facets]
= `@Facets`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
index 3c80d62..f9f7dbb 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/HomePage.adoc
@@ -1,3 +1,4 @@
+[#HomePage]
= `@HomePage`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/IsisSessionScope.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/IsisSessionScope.adoc
index 19438ec..35520ee 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/IsisSessionScope.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/IsisSessionScope.adoc
@@ -1,3 +1,4 @@
+[#IsisSessionScope]
= `@IsisSessionScope`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc
index b2c6348..e2243e8 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder.adoc
@@ -1,3 +1,4 @@
+[#MemberOrder]
= `@MemberOrder`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/name.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/name.adoc
index 1632640..fd9d817 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/name.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/name.adoc
@@ -7,7 +7,79 @@
// TODO: v2: replace @MemberOrder#name() with @PropertyLayout#group().
-Broadly speaking the `name` attribute is used to group or associate members together.
+The interpretation of the `name` attribute varies dependent on the type of object member it is annotated upon.
-As this is an important topic, there is xref:userguide:fun:ui.adoc#object-layout[chapter] in the user guide that discusses object layout in full.
+== Properties
+
+For properties, the `name` attribute is used to group properties together.
+It corresponds to a `<fieldset>` if using xref:userguide:fun:ui.adoc#object-layout[layout files].
+
+For example:
+
+[source,java]
+----
+import lombok.Getter;
+import lombok.Setter;
+
+public class Customer {
+
+ @MemberOrder(name = "Personal Details", sequence = "1.0")
+ private String firstName;
+
+ @MemberOrder(name = "Personal Details", sequence = "2.0")
+ private String lastName;
+
+ @MemberOrder(name = "Address", sequence = "1.0")
+ private String addressLine1;
+
+ @MemberOrder(name = "Address", sequence = "2.0")
+ private String addressLine2;
+
+ @MemberOrder(name = "Address", sequence = "3.0")
+ private String city;
+
+ @MemberOrder(name = "Address", sequence = "4.0")
+ private String zipCode;
+
+ // ...
+}
+----
+
+TIP: It's possible to combine `@MemberOrder` with xref:userguide:fun:ui.adoc#object-layout[layout file].
+Use the layout file to define the positioning of the fieldsets, and use `@MemberOrder` to organise the properties within the fieldset.
+
+== Actions
+
+For actions, the `name` attribute indicates the name of a property to associate the action with.
+
+TIP: For actions, `@Member#name()` and xref:refguide:applib-ant:Action.adoc#associateWith()` are the same.
+
+For example:
+
+[source,java]
+----
+import lombok.Getter;
+import lombok.Setter;
+
+public class Customer {
+
+ @MemberOrder(name = "Personal Details")
+ public Customer updateName(String firstName, String lastName) {
+ // ...
+ }
+
+ @MemberOrder(name = "Address")
+ public Customer changeAddress(String firstName, String lastName) {
+ // ...
+ }
+
+ // ...
+}
+----
+
+TIP: the xref:refguide:applib-ant:ActionLayout.adoc#position[`@ActionLayout#position()`] to indicate whether the action should be rendered beneath the property, or on its fieldset panel's header.
+
+== Collections
+
+The `name` attribute is ignored when annotated on collections.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/sequence.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/sequence.adoc
index e55a3db..b9862e3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/sequence.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/MemberOrder/sequence.adoc
@@ -7,6 +7,10 @@
// TODO: v2: replace @MemberOrder#sequence() with @PropertyLayout#sequence().
-Broadly speaking the `sequence` attribute orders members once they have been grouped.
+The `sequence` attribute orders members that have been grouped together.
-As this is an important topic, there is xref:userguide:fun:ui.adoc#object-layout[chapter] in the user guide that discusses object layout in full.
+* For properties, this means ordering properties within a property group (fieldset)
+
+* For actions, it means ordering actions that have been associated with the same property (or panel of that property's fieldset).
+
+For more on layouts, see the xref:userguide:fun:ui.adoc#object-layout[object layout] chapter in the user guide.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc
index 50cdf7e..d349441 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/MinLength.adoc
@@ -1,3 +1,4 @@
+[#MinLength]
= `@MinLength`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
index 1d4b13a..fbdfc4a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin.adoc
@@ -1,3 +1,4 @@
+[#Mixin]
= `@Mixin`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin/method.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin/method.adoc
index bf72c06..0c29d0b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin/method.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Mixin/method.adoc
@@ -5,7 +5,6 @@
:page-partial:
-
The `method` attribute specifies the name of the method to be treated as a "reserved" method name, meaning that the mixin's name should instead be inferred from the mixin's type.
For example:
@@ -16,16 +15,20 @@ For example:
public class Customer {
@Mixin(method="execute")
- public static class placeOrder {
-
- Customer customer;
- public placeOrder(Customer customer) { this.customer = customer; }
-
- public Customer execute(Product p, int quantity) { /* ... */ }
- public String disableExecute() { /* ... */ }
- public String validate0Execute() { /* ... */ }
+ public class placeOrder {
+
+ public Customer execute(Product p, int quantity) {
+ // ...
+ }
+ public String disableExecute() {
+ // ...
+ }
+ public String validate0Execute() {
+ // ...
+ }
}
- ...
+
+ // ...
)
----
@@ -35,7 +38,7 @@ When invoked programmatically, the code reads:
[source,java]
----
-mixin(Customer.placeOrder.class, someCustomer).execute(someProduct, 3);
+someCustomer.new placeOrder().execute(someProduct, 3);
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc
index 701f8fd..9be35ae 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/NotPersistent.adoc
@@ -1,3 +1,4 @@
+[#javax-jdo-annotation-NotPersistent]
= `@NotPersistent` (`javax.jdo`)
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc
index c291b31..0dc5992 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Nullable.adoc
@@ -1,3 +1,4 @@
+[#javax-annotation-Nullable]
= `@Nullable` (`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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc
index 1d308b7..d9d7392 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter.adoc
@@ -1,3 +1,4 @@
+[#Parameter]
= `@Parameter`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/fileAccept.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/fileAccept.adoc
index cea1049..1f445b8 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/fileAccept.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/fileAccept.adoc
@@ -7,28 +7,23 @@
The `fileAccept` attribute applies only to xref:refguide:applib-cm:classes/value-types.adoc#Blob[`Blob`]
-or xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`] parameters, indicating the type of file to accept when
-uploading a new value. The attribute is also supported on xref:refguide:applib-ant:Property.adoc#fileAccept[properties].
+or xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`] parameters, indicating the type of file to accept when uploading a new value.
+The attribute is also supported on xref:refguide:applib-ant:Property.adoc#fileAccept[properties].
For example:
[source,java]
----
public class Scanner {
+
public ScannedDocument newScan(
- @Parameter(fileAccept="image/*") // <1>
- final Blob scannedImage) {
- ...
+ @Parameter(
+ fileAccept="image/*" // <.>
+ )
+ final Blob scannedImage) {
+ // ...
}
}
----
-<1> as per link:http://www.w3schools.com/tags/att_input_accept.asp[reference docs], either a media type (such as
-`image/*`) or a file type extension (such as `.png`).
-
-
-
-
-
-
-
+<.> as per link:http://www.w3schools.com/tags/att_input_accept.asp[reference docs], either a media type (such as `image/*`) or a file type extension (such as `.png`).
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/maxLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/maxLength.adoc
index f48c0e0..703c215 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/maxLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/maxLength.adoc
@@ -6,8 +6,8 @@
-The `maxLength` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI). It is ignored if applied to parameters of any other type.
-
+The `maxLength` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).
+It is ignored if applied to parameters of any other type.
For example:
@@ -24,9 +24,6 @@ public class CustomerRepository {
}
----
-
-
-
== See also
This attribute can also be applied to xref:refguide:applib-ant:Property.adoc#maxLength[properties].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/mustSatisfy.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/mustSatisfy.adoc
index 068f047..69ad273 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/mustSatisfy.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/mustSatisfy.adoc
@@ -6,50 +6,62 @@
-The `mustSatisfy` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object. The attribute is also supported on xref:refguide:applib-ant:Property.adoc#mustSatisfy[properties].
+The `mustSatisfy` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
+The attribute is also supported on xref:refguide:applib-ant:Property.adoc#mustSatisfy[properties].
[TIP]
====
The specification implementations can (of course) be reused between parameters and xref:refguide:applib-ant:Property.adoc#mustSatisfy[properties].
====
-The `Specification` is consulted during validation, being passed the proposed value. If the proposed value fails, then the value returned is the used as the invalidity reason.
+The `Specification` is consulted during validation, being passed the proposed value.
+If the proposed value fails, then the value returned is the used as the invalidity reason.
For example:
[source,java]
+.StartWithCapitalLetterSpecification.java
----
public class StartWithCapitalLetterSpecification
- extends AbstractSpecification<String> { // <1>
+ extends AbstractSpecification<String> { // <.>
+
public String satisfiesSafely(String proposed) {
return "".equals(proposed)
? "Empty string"
: !Character.isUpperCase(proposed.charAt(0))
? "Does not start with a capital letter"
: null;
+
}
}
+----
+<.> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values.
+The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
+
+can then be used:
+
+[source,java]
+.CustomerRepository.java
+----
public class CustomerRepository {
public Customer newCustomer(
- @Parameter(
- mustSatisfy=StartWithCapitalLetterSpecification.class
- )
- @ParameterLayout(named="First Name")
- final String firstName,
- @Parameter(
- mustSatisfy=StartWithCapitalLetterSpecification.class
- )
- @ParameterLayout(named="Last Name")
- final String lastName) {
- ...
+ @Parameter(
+ mustSatisfy=StartWithCapitalLetterSpecification.class
+ )
+ final String firstName,
+ @Parameter(
+ mustSatisfy=StartWithCapitalLetterSpecification.class
+ )
+ final String lastName) {
+ // ...
}
...
}
----
-<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values. The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
-
-It is also possible to provide translatable reasons. Rather than implement `Specification`, instead implement `Specification2` which defines the API:
+It is also possible to provide translatable reasons.
+Rather than implement `Specification`, instead implement `Specification2`.
+This defines the API:
[source,java]
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/optionality.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/optionality.adoc
index 9c10e9e..e3596dd 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/optionality.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/optionality.adoc
@@ -7,12 +7,14 @@
-By default, Apache Isis assumes that all parameters of an action are required (mandatory). The `optionality` attribute allows this to be relaxed. The attribute is also supported for xref:refguide:applib-ant:Property.adoc#optionality[properties].
-
+By default, Apache Isis assumes that all parameters of an action are required (mandatory).
+The `optionality` attribute allows this to be relaxed.
+The attribute is also supported for xref:refguide:applib-ant:Property.adoc#optionality[properties].
[TIP]
====
-The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
+The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero).
+If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
====
The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
@@ -24,19 +26,16 @@ For example:
public class Customer {
public Order placeOrder(
final Product product,
- @ParameterLayout(named = "Quantity")
final int quantity,
@Parameter(optionality = Optionality.OPTIONAL)
- @ParameterLayout(named = "Special Instructions")
- final String instr) {
+ final String specialInstructions) {
...
}
...
}
----
-
-[NOTE]
+[TIP]
====
It is also possible to specify optionality using xref:refguide:applib-ant:Nullable.adoc[`@Nullable`] annotation.
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/regexPattern.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/regexPattern.adoc
index 96bb588..6d85481 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/regexPattern.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Parameter/regexPattern.adoc
@@ -4,17 +4,15 @@
: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 [...]
:page-partial:
-
-
There are three attributes related to enforcing regular expressions:
-* The `regexPattern` attribute validates the contents of any string parameter with respect to a regular expression pattern. It is ignored if applied to parameters of any other type.
+* The `regexPattern` attribute validates the contents of any string parameter with respect to a regular expression pattern.
+It is ignored if applied to parameters of any other type.
-* The `regexPatternFlags` attribute specifies flags that modify the handling of the pattern. The values are those
-that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
+* The `regexPatternFlags` attribute specifies flags that modify the handling of the pattern.
+The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
-* The related `regexPatternReplacement` attribute specifies the error message to show if
-the provided argument does not match the regex pattern.
+* The related `regexPatternReplacement` attribute specifies the error message to show if the provided argument does not match the regex pattern.
For example:
@@ -25,7 +23,9 @@ public class Customer {
@Parameter(
regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
regexPatternFlags = Pattern.CASE_INSENSITIVE,
- regexPatternReplacement = "Must be valid email address (containing a '@') symbol" // <1>
+ regexPatternReplacement =
+ "Must be valid email address " +
+ "(containing a '@') symbol" // <.>
)
@ParameterLayout(named = "Email")
final String email) {
@@ -33,9 +33,7 @@ public class Customer {
}
)
----
-<1> Note that there is currently no i18n support for this phrase.
-
-
+<.> Note that there is currently no i18n support for this phrase.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
index 2302640..0202e96 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout.adoc
@@ -1,3 +1,4 @@
+[#ParameterLayout]
= `@ParameterLayout`
: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 [...]
@@ -44,7 +45,7 @@ The only reason then to name the parameter is if the desired name is a reserved
+
Whether to HTML escape the name of this parameter.
-<.> xref:refguide:applib-ant:ParameterLayout.adoc#renderedAsDayBefore[`renderedAsDayBefore()`]
+<.> xref:refguide:applib-ant:ParameterLayout.adoc#renderDay[`renderDay()`]
+
For date parameters only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
@@ -92,5 +93,5 @@ include::ParameterLayout/describedAs.adoc[leveloffset=+1]
include::ParameterLayout/labelPosition.adoc[leveloffset=+1]
include::ParameterLayout/multiLine.adoc[leveloffset=+1]
include::ParameterLayout/named.adoc[leveloffset=+1]
-include::ParameterLayout/renderedAsDayBefore.adoc[leveloffset=+1]
+include::ParameterLayout/renderDay.adoc[leveloffset=+1]
include::ParameterLayout/typicalLength.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/cssClass.adoc
index 9070e31..396568b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/cssClass.adoc
@@ -5,31 +5,28 @@
:page-partial:
-
-
The `cssClass` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter. xref:refguide:config:application-specific/application-css.adoc[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
-
For example:
[source,java]
----
public class ToDoItem {
+
public ToDoItem postpone(
@ParameterLayout(
- named="until",
cssClass="x-key"
)
- LocalDate until
- ) { /* ... */ }
- ...
+ LocalDate until ) {
+ // ...
+ }
+
+ // ...
}
----
-
== See also
-
This attribute can also be applied to:
* xref:refguide:applib-ant:DomainObjectLayout.adoc#cssClass[domain objects]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/describedAs.adoc
index 1432a79..3893dd3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/describedAs.adoc
@@ -16,16 +16,17 @@ For example:
[source,java]
----
public class Customer {
+
public Order placeOrder(
- Product product,
- @ParameterLayout(
- named="Quantity",
- describedAs="The quantity of the product being ordered"
- )
- int quantity) {
- ...
+ Product product,
+ @ParameterLayout(
+ describedAs = "The quantity of the product being ordered"
+ )
+ int quantity) {
+ // ...
}
- ...
+
+ // ...
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/labelPosition.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/labelPosition.adoc
index 7fa0233..dc18c6a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/labelPosition.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/labelPosition.adoc
@@ -8,7 +8,8 @@
The `labelPosition` attribute determines the positioning of labels for parameters.
-The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:refguide:applib-ant:ParameterLayout.adoc#multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.
+The one exception is xref:refguide:applib-ant:ParameterLayout.adoc#multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
For boolean parameters a positioning of `RIGHT` is also allowed; this is ignored for all other types.
@@ -19,26 +20,23 @@ For example:
[source,java]
----
public class Order {
+
public Order changeStatus(
- OrderStatus newStatus
- @Parameter(
- optionality=Optionality.OPTIONAL
- )
+ OrderStatus newStatus,
+ @Nullable
@ParameterLayout(
- named="Reason",
labelPosition=LabelPosition.TOP
)
String reason) {
- ...
+ // ...
}
- ...
+
+ // ...
}
----
-
To get an idea of how these are rendered (in the xref:vw:ROOT:about.adoc[Wicket viewer]), see xref:refguide:applib-ant:PropertyLayout.adoc#labelPosition[PropertyLayout#labelPosition].
-
== See also
This attribute can also be specified for xref:refguide:applib-ant:PropertyLayout.adoc#labelPosition[properties].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/multiLine.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/multiLine.adoc
index 67eff00..d8da321 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/multiLine.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/multiLine.adoc
@@ -6,22 +6,25 @@
-The `multiLine` attribute specifies that the text field for a string parameter should span multiple lines. It is ignored for other parameter types. The attribute is also supported for xref:refguide:applib-ant:PropertyLayout.adoc#multiLine[properties].
+The `multiLine` attribute specifies that the text field for a string parameter should span multiple lines.
+It is ignored for other parameter types.
+The attribute is also supported for xref:refguide:applib-ant:PropertyLayout.adoc#multiLine[properties].
For example:
[source,java]
----
public class BugReport {
+
public BugReport updateStepsToReproduce(
- @Parameter(named="Steps")
- @ParameterLayout(
- numberOfLines=10
- )
- final String steps) {
- ...
+ @ParameterLayout(
+ numberOfLines=10
+ )
+ final String steps) {
+ // ...
}
- ...
+
+ // ...
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/named.adoc
index 5cdb097..001e543 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/named.adoc
@@ -5,17 +5,15 @@
:page-partial:
-
The `named` attribute explicitly specifies the action parameter's name.
-Unlike most other aspects of the Apache Isis metamodel, the name of method parameters cannot (prior to Java 8, at least) be inferred from the Java source code.
-Without other information, Apache Isis uses the object's type (`int`, `String` etc) as the name instead.
-This can be sufficient for application-specific reference types (eg `ToDoItem`) but is generally not sufficient for primitives and other value types.
-The `named` attribute is therefore often required to specify the parameter name.
-
-As of Java 8, the Java reflection API has been extended; use with the `-parameters` compile flag for javac.
-
+In most cases -- so long as the `--parameters` compile flag is passed to javac -- then this attribute is not required.
+[TIP]
+====
+We recommend that you only use this attribute when the desired name cannot be used in Java source code.
+Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
By default the name is HTML escaped.
To allow HTML markup, set the related `namedEscaped` attribute to `false`.
@@ -26,20 +24,18 @@ For example:
----
public class Customer {
public Order placeOrder(
- final Product product
- ,@ParameterLayout(named="Quantity")
- final int quantity) {
- Order order = newTransientInstance(Order.class);
- order.modifyCustomer(this);
- order.modifyProduct(product);
- order.setQuantity(quantity);
- return order;
+ final Product product,
+ @ParameterLayout(named="Package ?")
+ final boolean packageUp) {
+ Order order = Order.forCustomer(this)
+ .ofProduct(product)
+ .withPackage(packageUp);
+ return repository.persistAndFlush(order);
}
...
}
----
-
[TIP]
====
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/renderedAsDayBefore.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/renderDay.adoc
similarity index 68%
rename from api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/renderedAsDayBefore.adoc
rename to api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/renderDay.adoc
index d00885b..037977e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/renderedAsDayBefore.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/renderDay.adoc
@@ -1,17 +1,16 @@
-[#renderedAsDayBefore]
-= `renderedAsDayBefore()`
+[#renderDay]
+= `renderDay()`
: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 [...]
:page-partial:
-The `renderedAsDayBefore` attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object.
+The `renderDay` attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object.
It is ignored for parameters of other types.
This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time.
-In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2.
-Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
+In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
@@ -22,21 +21,21 @@ For example:
[source,java]
----
public class Tenancy {
+
public void changeDates(
- @ParameterLayout(named="Start Date")
- LocalDate startDate,
- @ParameterLayout(
- named="End Date",
- renderedAsDayBefore=true
- )
- LocalDate endDate) {
- ...
+ LocalDate startDate,
+ @ParameterLayout(
+ renderDay = RenderDay.AS_DAY_BEFORE
+ )
+ LocalDate endDate) {
+ // ...
}
+
+ // ...
}
----
-
== See also
-This attribute is also supported for xref:refguide:applib-ant:PropertyLayout.adoc#renderedAsDayBefore[properties].
+This attribute is also supported for xref:refguide:applib-ant:PropertyLayout.adoc#renderDay[properties].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/typicalLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/typicalLength.adoc
index 0fc636c..ead0db3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/typicalLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ParameterLayout/typicalLength.adoc
@@ -18,22 +18,21 @@ For example:
[source,java]
----
public class Customer {
+
public Customer updateName(
@Parameter(maxLength=30)
@ParameterLayout(
- named="First name",
typicalLength=20
)
final String firstName,
@Parameter(maxLength=30)
@ParameterLayout(
- named="Last name",
typicalLength=20
)
final String lastName) {
- ...
+ // ...
}
- ...
+
+ // ...
}
----
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Pattern.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Pattern.adoc
index f6bfe7f..ff656ef 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Pattern.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Pattern.adoc
@@ -1,3 +1,4 @@
+[#javax-validation-constraints-Pattern]
= `@Pattern` (`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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc
index 946abc9..57a6962 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PersistenceCapable.adoc
@@ -1,3 +1,4 @@
+[#javax-jdo-annotation-PersistenceCapable]
= `@PersistenceCapable` (`javax.jdo`)
: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 [...]
@@ -24,7 +25,7 @@ This can appear in several contexts, including:
(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
-* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (in general and in particular if xref:vw:ROOT:features.adoc#hints-and-copy-url[copying URLs])
+* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer]
* in XML snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PrimaryKey.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PrimaryKey.adoc
index b84f578..2164f5b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PrimaryKey.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PrimaryKey.adoc
@@ -1,3 +1,4 @@
+[#javax-jdo-annotation-PrimaryKey]
= `@PrimaryKey` (`javax.jdo`)
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc
index fbccefc..9bda863 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Programmatic.adoc
@@ -1,3 +1,4 @@
+[#Programmatic]
= `@Programmatic`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc
index f548a1a..fa28768 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property.adoc
@@ -1,3 +1,4 @@
+[#Property]
= `@Property`
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/domainEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/domainEvent.adoc
index 45b3d33..191dce7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/domainEvent.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/domainEvent.adoc
@@ -21,25 +21,38 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
- @Property()
- public LocalDate getDueBy() { /* ... */ }
- ...
+
+ @Property
+ @Getter @Setter
+ private LocalDate dueBy;
+
+ // ...
}
----
The `domainEvent` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
- public static class DueByChangedEvent extends PropertyDomainEvent<ToDoItem, LocalDate> { } // <1>
+
+ public static class DueByChangedEvent
+ extends PropertyDomainEvent<ToDoItem, LocalDate> { } // <.>
+
@Property(domainEvent=ToDoItem.DueByChangedEvent)
- public LocalDate getDueBy() { /* ... */ }
- ...
+ @Getter @Setter
+ private LocalDate dueBy;
+
+ // ...
}
----
<1> inherit from `PropertyDomainEvent<T,P>` where `T` is the type of the domain object being interacted with, and `P` is the type of the property (`LocalDate` in this example)
@@ -52,7 +65,6 @@ The framework provides a no-arg constructor and will initialize the domain event
This substantially reduces the boilerplate in the subclasses because no explicit constructor is required..
====
-
== Subscribers
Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
@@ -66,9 +78,10 @@ import org.springframework.stereotype.Service;
@Service
public class SomeSubscriber {
+
@EventListener(PropertyDomainEvent.class)
public void on(PropertyDomainEvent ev) {
- ...
+ // ...
}
}
----
@@ -82,9 +95,10 @@ import org.springframework.stereotype.Service;
@Service
public class SomeSubscriber {
+
@EventListener(ToDoItem.DueByChangedEvent.class)
public void on(ToDoItem.DueByChangedEvent ev) {
- ...
+ // ...
}
}
----
@@ -134,9 +148,6 @@ public class SomeSubscriber {
It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-
-
-
== Default, Doop and Noop events
If the `domainEvent` attribute is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`), then the framework will, by default, post an event.
@@ -148,16 +159,11 @@ The framework provides `PropertyDomainEvent.Doop` as such a subclass, so setting
And, conversely, the framework also provides `PropertyDomainEvent.Noop`; if `domainEvent` attribute is set to this class, then no event will be posted.
-
-
-
-
== Raising events programmatically
Normally events are only raised for interactions through the UI.
However, events can be raised programmatically by wrapping the target object using the xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`] service.
-
== See also
This attribute is also supported for:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/editing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/editing.adoc
index 2de559f..1a1c4f2 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/editing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/editing.adoc
@@ -11,35 +11,34 @@ The related `editingDisabledReason` attribute specifies the a hard-coded reason
Whether a property is enabled or disabled depends upon these factors:
-* whether the domain object has been configured as immutable through the xref:refguide:DomainObject/editing.adoc[`@DomainObject#editing()`] attribute
+* whether the domain object has been configured as immutable through the xref:refguide:applib-ant:DomainObject.adoc#editing[`@DomainObject#editing()`] attribute
-* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:refguide:config:configuring-core.adoc[configuration property] `isis.objects.editing`. If set to `false`, then the object's properties (and collections) are __not__ editable
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.editing['isis.applib.annotation.domain-object.editing'] configuration property.
+If set to `false`, then the object's properties (and collections) are __not__ editable
* else, then the value of the `@Property(editing=...)` attribute itself
-* else, the result of invoking any supporting xref:refguide:applib-cm:rgcms.adoc#\_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:refguide:applib-cm:methods/prefixes.adoc#disable[`disable...()`] supporting methods
Thus, to make a property read-only even if the object would otherwise be editable, use:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
@Property(
editing=Editing.DISABLED,
- editingDisabledReason="The credit rating is derived from multiple factors"
+ editingDisabledReason =
+ "The credit rating is derived from multiple factors"
)
- public int getInitialCreditRating(){ /* ... */ }
- public void setInitialCreditRating(int initialCreditRating) { /* ... */ }
+ @Getter @Setter
+ private int initialCreditRating;
}
----
-[NOTE]
-====
-To reiterate, it is _not_ possible to enable editing for a property if editing has been disabled at the object-level.
-====
-
-
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/fileAccept.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/fileAccept.adoc
index ab2942e..6263025 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/fileAccept.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/fileAccept.adoc
@@ -5,25 +5,25 @@
:page-partial:
-
The `fileAccept` attribute applies only to xref:refguide:applib-cm:classes/value-types.adoc#Blob[`Blob`] or xref:refguide:applib-cm:classes/value-types.adoc#Clob[`Clob`] parameters, indicating the type of file to accept when uploading a new value.
The attribute is also supported on xref:refguide:applib-ant:Parameter.adoc#fileAccept[parameters].
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ScannedDocument {
@Property(fileAccept="image/*") // <1>
+ @Getter @Setter
private Blob scannedImage;
- // getters and setters omitted
}
----
-<1> as per link:http://www.w3schools.com/tags/att_input_accept.asp[reference docs], either a media type (such as
-`image/*`) or a file type extension (such as `.png`).
+<1> as per link:http://www.w3schools.com/tags/att_input_accept.asp[reference docs], either a media type (such as `image/*`) or a file type extension (such as `.png`).
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/hidden.adoc
index cc92e34..b1142f1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/hidden.adoc
@@ -8,23 +8,25 @@
Properties can be hidden at the domain-level, indicating that they are not visible to the end-user.
-
[TIP]
====
It is also possible to use xref:refguide:applib-ant:Property.adoc#hidden[`@Property#hidden()`] to hide an action at the domain layer.
-Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@Property(hidden=Where.EVERYWHERE)
- public int getInternalId() { /* ... */ }
- @Property(hidden=Where.ALL_TABLES)
- public void updateStatus() { /* ... */ }
- ...
+ @Getter @Setter
+ private int internalId;
+
+ // ...
}
----
@@ -56,19 +58,16 @@ The property should be hidden when displayed as a column of a table, either an o
This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
* `Where.NOWHERE` +
-+
-The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
-
-For example, if a property is annotated with xref:refguide:applib-ant:Title.adoc[`@Title`], then normally this should be hidden from all
-tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
++ The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
+For example, if a property is annotated with xref:refguide:applib-ant:Title.adoc[`@Title`], then normally this should be hidden from all tables.
+Annotating with `@Property(where=Where.NOWHERE)` overrides this.
[NOTE]
====
The xref:vro:ROOT:about.adoc[RestfulObjects viewer] has only partial support for these `Where` enums.
====
-
== See also
This attribute can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/maxLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/maxLength.adoc
index 1e4e053..bba6e00 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/maxLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/maxLength.adoc
@@ -9,7 +9,6 @@
The `maxLength` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).
The attribute It is ignored if applied to properties of any other type.
-
That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:refguide:applib-ant:Column.adoc[`@Column`] will in any case need to be specified.
Apache Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
@@ -17,18 +16,21 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@javax.jdo.annotations.Column(length=30)
- public String getFirstName() { /* ... */ }
- public void setFirstName(String firstName) { /* ... */ }
- ...
+ @Getter @Setter
+ private String firstName;
+
+ // ...
}
----
In this case there is therefore no need for the `@Property#maxLength` attribute.
-
-
== Non-persistent properties
Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model).
@@ -39,17 +41,17 @@ For example:
[source,java]
----
public class Customer {
- @javax.jdo.annotation.NotPersistent // <1>
+
+ @javax.jdo.annotation.NotPersistent // <.>
@Property(maxLength=100)
- public String getFullName() { /* ... */ } // <2>
- public void setFullName(String fullName) { /* ... */ } // <3>
+ public String getFullName() { /* ... */ } // <2>
+ public void setFullName(String fullName) { /* ... */ } // <3>
...
}
----
-<1> a non persisted (derived) property
-<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
-<3> implementation would most likely parse the input and update the constituent parts
-
+<.> a non persisted (derived) property
+<.> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
+<.> implementation would most likely parse the input and update the constituent parts
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc
index c7fc470..c8cc4e4 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mementoSerialization.adoc
@@ -5,24 +5,25 @@
:page-partial:
-
-
The `mementoSerialization` attribute indicates whether the property should be included/excluded from any snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`].
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Order {
+
@Property(mementoSerialization=EXCLUDED)
- public Order getPreviousOrder() {...}
- public void setPreviousOrder(Order previousOrder) {...}
- ...
+ @Getter @Setter
+ private Order previousOrder;
+
+ // ...
}
----
-
Alternatively, if the property is derived, then providing only a "getter" will also work:
[source,java]
@@ -33,8 +34,7 @@ public class Order {
}
----
-
== See also
-This attribute is also supported for xref:refguide:applib-ant:Collection.adoc#mementoSerializationp[collections].
+This attribute is also supported for xref:refguide:applib-ant:Collection.adoc#mementoSerialization[collections].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mustSatisfy.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mustSatisfy.adoc
index 6b9d553..a407199 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mustSatisfy.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/mustSatisfy.adoc
@@ -6,23 +6,23 @@
-
The `mustSatisfy` attribute allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
- The attribute is also supported on xref:refguide:applib-ant:Parameter.adoc#mustSatisfy[parameters].
+The attribute is also supported on xref:refguide:applib-ant:Parameter.adoc#mustSatisfy[parameters].
[TIP]
====
The specification implementations can (of course) be reused between properties and xref:refguide:applib-ant:Parameter.adoc#mustSatisfy[parameters].
====
-The `Specification` is consulted during validation, being passed the proposed value. If the proposed value fails, then the value returned is the used as the invalidity reason.
+The `Specification` is consulted during validation, being passed the proposed value.
+If the proposed value fails, then the value returned is the used as the invalidity reason.
For example:
[source,java]
----
public class StartWithCapitalLetterSpecification
- extends AbstractSpecification<String> { // <1>
+ extends AbstractSpecification<String> { // <.>
public String satisfiesSafely(String proposed) {
return "".equals(proposed)
? "Empty string"
@@ -31,15 +31,25 @@ public class StartWithCapitalLetterSpecification
: null;
}
}
+----
+<.> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values.
+
+where:
+
+[source,java]
+----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@Property(mustSatisfy=StartWithCapitalLetterSpecification.class)
- public String getFirstName() { /* ... */ }
- ...
+ @Getter @Setter
+ private String firstName;
+
+ // ...
}
----
-<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values.
-The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
-
It is also possible to provide translatable reasons.
Rather than implement `Specification`, instead implement `Specification2` which defines the API:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/optionality.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/optionality.adoc
index 44df4d2..01dd9f7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/optionality.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/optionality.adoc
@@ -5,9 +5,6 @@
:page-partial:
-
-
-
By default, Apache Isis assumes that all properties of an domain object or view model are required (mandatory).
The `optionality` attribute allows this to be relaxed.
The attribute is also supported for xref:refguide:applib-ant:Parameter.adoc#optionality[parameters].
@@ -22,17 +19,21 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@javax.jdo.annotations.Column(allowsNull="true")
- public String getMiddleInitial() { /* ... */ }
- public void setMiddleInitial(String middleInitial) { /* ... */ }
- ...
+ @Getter @Setter
+ private String middleInitial;
+
+ // ...
}
----
In this case there is no need for the `@Property#optionality` attribute.
-
== Mismatched defaults
If the `@Column#allowsNull` attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Isis' defaults and JDO's defaults differ.
@@ -41,7 +42,6 @@ Specifically, Isis always assumes properties are mandatory, whereas JDO specifie
When Apache Isis initializes it checks for these mismatches during its metamodel validation phase, and will fail to boot ("fail-fast") if there is a mismatch.
The fix is usually to add the `@Column#allowsNull()` annotation/attribute.
-
== Superclass inheritance type
There is one case (at least) it may be necessary to annotate the property with both `@Column#allowsNull` and also `@Property#optionality()`.
@@ -59,6 +59,7 @@ public abstract class PaymentMethod {
@javax.jdo.annotations.PersistenceCapable
@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
public class CreditCardPaymentMethod extends PaymentMethod {
+
private String cardNumber;
@javax.jdo.annotations.Column(allowsNull="true")
@Property(optionality=Optionality.MANDATORY)
@@ -75,18 +76,18 @@ Alternatively, you could rely on the fact that Apache Isis never looks at fields
@javax.jdo.annotations.PersistenceCapable
@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
public class CreditCardPaymentMethod extends PaymentMethod {
+
@javax.jdo.annotations.Column(allowsNull="true")
private String cardNumber;
+
public String getCardNumber() { return this.cardNumber; }
public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
- ...
+
+ // ...
}
----
-However this at first glance this might be read as eing that the property is optional whereas Isis' default (required) applies.
-Also, in the future Apache Isis may be extended to support reading annotations from fields.
-
-
+However this at first glance this might be read as meaning that the property is optional whereas Apache Isis' default (required) applies.
== Non-persistent properties
@@ -98,17 +99,22 @@ For example:
[source,java]
----
public class Customer {
- @javax.jdo.annotation.NotPersistent // <1>
+
+ @javax.jdo.annotation.NotPersistent // <.>
@Property(optionality=Optionality.OPTIONAL)
- public String getFullName() { /* ... */ } // <2>
- public void setFullName(String fullName) { /* ... */ } // <3>
- ...
+ public String getFullName() { // <.>
+ // ...
+ }
+ public void setFullName(String fullName) { // <.>
+ // ...
+ }
+
+ // ...
}
----
-<1> a non persisted (derived) property
-<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
-<3> implementation would most likely parse the input and update the constituent parts
-
+<.> a non persisted (derived) property
+<.> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
+<.> implementation would most likely parse the input and update the constituent parts
[TIP]
====
@@ -118,24 +124,6 @@ If optionality is required, then use the corresponding wrapper class (e.g. `java
The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- final Product product,
- @ParameterLayout(named = "Quantity")
- final int quantity,
- @Parameter(optionality = Optionality.OPTIONAL)
- @ParameterLayout(named = "Special Instructions")
- final String instr) {
- ...
- }
- ...
-}
-----
-
[NOTE]
====
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/projecting.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/projecting.adoc
index 6585815..c3af1ec 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/projecting.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/projecting.adoc
@@ -20,20 +20,20 @@ For example:
public InvoiceSummary {
@Property(
- projecting = Projecting.PROJECTED // <1>
- hidden = Where.EVERYWHERE // <2>
+ projecting = Projecting.PROJECTED // <.>
+ hidden = Where.EVERYWHERE // <.>
}
@Getter @Setter
private Invoice invoice;
- public LocalDate getDueDate() { // <3>
+ public LocalDate getDueDate() { // <.>
return invoice.getDueDate();
}
...
}
----
-<1> indicates that this property holds a reference to the underlying entity
-<2> the underlying entity is typically (though not necessarily) hidden
-<3> typical implementation of the properties of the underlying entity that are being projected in the view model.
+<.> indicates that this property holds a reference to the underlying entity
+<.> the underlying entity is typically (though not necessarily) hidden
+<.> typical implementation of the properties of the underlying entity that are being projected in the view model.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc
index 6405942..dca4112 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc
@@ -5,8 +5,6 @@
:page-partial:
-
-
The `publishing` attribute determines whether and how a property edit is published via the registered implementation of xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
@@ -22,22 +20,25 @@ no property edits are published
If there is no configuration property in `application.properties` then publishing is automatically enabled.
-This default can be overridden on an property-by-property basis; if `publishing()` is set to `ENABLED` then the
-property edit is published irrespective of the configured value; if set to `DISABLED` then the property edit is
-_not_ published, again irrespective of the configured value.
+This default can be overridden on an property-by-property basis; if `publishing()` is set to `ENABLED` then the property edit is published irrespective of the configured value; if set to `DISABLED` then the property edit is _not_ published, again irrespective of the configured value.
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Order {
- @Property(publishing=Publishing.ENABLED) // <1>
- public int getQuantity() { /* ... */ }
- public void setQuantity(int quantity) { /* ... */ }
+
+ @Property(publishing=Publishing.ENABLED) // <.>
+ @Getter @Setter
+ private int quantity;
+
+ // ...
}
----
-<1> because set to enabled, will be published irrespective of the configured value.
-
+<.> because set to enabled, will be published irrespective of the configured value.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/regexPattern.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/regexPattern.adoc
index 9a6c885..d989da9 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/regexPattern.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/regexPattern.adoc
@@ -20,18 +20,22 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@Property(
regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
regexPatternFlags=Pattern.CASE_INSENSITIVE,
- regexPatternReplacement = "Must be valid email address (containing a '@') symbol" // <1>
+ regexPatternReplacement =
+ "Must be valid email address (containing a '@') symbol" // <.>
)
- public String getEmail() { /* ... */ }
+ @Getter @Setter
+ private String email;
}
----
-<1> Note that there is currently no i18n support for this phrase.
-
-
+<.> Note that there is currently no i18n support for this phrase.
== See also
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 280eab5..57f516e 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
@@ -1,3 +1,4 @@
+[#PropertyLayout]
= `@PropertyLayout`
: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 [...]
@@ -54,7 +55,7 @@ Whether a property should be used as the navigable parent (parent breadcrumb) of
+
How a property prompt should be displayed within the UI
-<.> xref:refguide:applib-ant:PropertyLayout.adoc#renderedAsDayBefore[`renderedAsDayBefore()`]
+<.> xref:refguide:applib-ant:PropertyLayout.adoc#renderDay[`renderDay()`]
+
For date properties only, render the date as one day prior to the actually stored date.
@@ -123,6 +124,6 @@ include::PropertyLayout/multiLine.adoc[leveloffset=+1]
include::PropertyLayout/named.adoc[leveloffset=+1]
include::PropertyLayout/navigable.adoc[leveloffset=+1]
include::PropertyLayout/promptStyle.adoc[leveloffset=+1]
-include::PropertyLayout/renderedAsDayBefore.adoc[leveloffset=+1]
+include::PropertyLayout/renderDay.adoc[leveloffset=+1]
include::PropertyLayout/typicalLength.adoc[leveloffset=+1]
include::PropertyLayout/repainting.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc
index 8ea9f87..da63b87 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/cssClass.adoc
@@ -12,20 +12,23 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@PropertyLayout(cssClass="x-key")
- public LocalDate getDueBy() { /* ... */ }
+ @Getter @Setter
+ private LocalDate dueBy;
+
+ // ...
}
----
-
-
-
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
== See also
This attribute can also be applied to:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc
index a9763e6..fa65fae 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/describedAs.adoc
@@ -13,9 +13,14 @@ For example:
[source,java]
----
public class Customer {
- @PropertyLayout(describedAs="The name that the customer has indicated that they wish to be " +
- "addressed as (e.g. Johnny rather than Jonathan)")
- public String getFirstName() { /* ... */ }
+
+ @PropertyLayout(
+ describedAs = "The name that the customer has indicated " +
+ "that they wish to be addressed as " +
+ "(e.g. Johnny rather than Jonathan)")
+ private String firstName;
+
+ // ...
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc
index 8cc26f4..3151c79 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/hidden.adoc
@@ -5,7 +5,6 @@
:page-partial:
-
The `hidden` attribute indicates where (in the UI) the property should be hidden from the user.
[TIP]
@@ -14,17 +13,22 @@ It is also possible to use xref:refguide:applib-ant:PropertyLayout.adoc#hidden[`
Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
====
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@PropertyLayout(
hidden=Where.ALL_TABLES
)
- public int getInternalId() { /* ... */ }
- ...
+ @Getter @Setter
+ private int internalId;
+
+ // ...
}
----
@@ -52,22 +56,21 @@ The property should be hidden when displayed as a column of a table showing a st
* `Where.ALL_TABLES`
+
-The property should be hidden when displayed as a column of a table, either an object's * collection or a standalone list. This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
+The property should be hidden when displayed as a column of a table, either an object's * collection or a standalone list.
+This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
* `Where.NOWHERE`
+
The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden.
-For example, if a property is annotated with xref:refguide:applib-ant:Title.adoc[`@Title`], then normally this should be hidden from all
-tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
-
+For example, if a property is annotated with xref:refguide:applib-ant:Title.adoc[`@Title`], then normally this should be hidden from all tables.
+Annotating with `@Property(where=Where.NOWHERE)` overrides this.
[NOTE]
====
The xref:vro:ROOT:about.adoc[RestfulObjects viewer] has only partial support for these `Where` enums.
====
-
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
index 0495834..668566a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
@@ -6,7 +6,6 @@
-
The `labelPosition` attribute determines the positioning of labels for properties.
The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.
@@ -20,18 +19,22 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@PropertyLayout(
labelPosition=LabelPosition.TOP
)
- public String getDescription() { /* ... */ }
- public void setDescription(String description) { /* ... */ }
- ...
+ @Getter @Setter
+ private String description;
+
+ // ...
}
----
-
-To get an idea of how these are rendered (in the xref:vw:ROOT:about.adoc[Wicket viewer]), we can look at the http://github.com/apache/isis-app-todoapp[TodoApp] that happens to have examples of most of these various label positions.
+To get an idea of how these are rendered (in the xref:vw:ROOT:about.adoc[Wicket viewer]), we can look at some examples of most of these various label positions.
The default `LEFT` label positioning is used by the `cost` property:
@@ -56,12 +59,8 @@ Moving the label to the `RIGHT` looks like:
image::reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png[width="720px",link="{imagesdir}/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png"]
+== Default settings
-
-
-[TIP]
-.Specifying a default setting for label positions
-====
If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
Instead, a default can be specified using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property-layout.label-position[`isis.applib.annotation.property-layout.label-position`] configuration property:
@@ -80,16 +79,14 @@ or
isis.applib.annotation.property-layout.label-position=LEFT
----
-If these are not present then Apache Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
-====
+If these are not present then Apache Isis will render according to internal defaults.
+At the time of writing, this means labels are to the left for all datatypes except multiline strings.
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
-
== See also
This attribute can also be specified for xref:refguide:applib-ant:ParameterLayout.adoc#labelPosition[parameters].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc
index e5a2a65..ff68e54 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/multiLine.adoc
@@ -5,25 +5,31 @@
:page-partial:
-The `multiLine` attribute specifies that the text field for a string property should span multiple lines. It is ignored for other property types. The attribute is also supported for xref:refguide:applib-ant:ParameterLayout.adoc#multiLine[parameters].
+The `multiLine` attribute specifies that the text field for a string property should span multiple lines.
+It is ignored for other property types.
+The attribute is also supported for xref:refguide:applib-ant:ParameterLayout.adoc#multiLine[parameters].
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class BugReport {
+
@PropertyLayout(
numberOfLines=10
)
- public String getStepsToReproduce() { /* ... */ }
- public void setStepsToReproduce(String stepsToReproduce) { /* ... */ }
- ...
+ @Getter @Setter
+ private String stepsToReproduce;
+
+ // ...
}
----
Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
-
[NOTE]
====
If set > 1 (as would normally be the case), then the default xref:refguide:applib-ant:PropertyLayout.adoc#labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc
index 473f5c3..8d0c9e4 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/named.adoc
@@ -9,11 +9,10 @@ The `named` attribute explicitly specifies the property's name, overriding the n
[TIP]
====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code.
+We recommend that you only use this attribute when the desired name cannot be used in Java source code.
Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
====
-
By default the name is HTML escaped.
To allow HTML markup, set the related `namedEscaped` attribute to `false`.
@@ -21,26 +20,28 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ToDoItem {
+
@PropertyLayout(
named="Description of this <i>item</i>",
namedEscaped=false
)
- public String getDescription() { /* ... */ }
- ...
+ @Getter @Setter
+ private String description;
+
+ // ...
}
----
-
-
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
The framework also provides a separate, powerful mechanism for xref:userguide:btb:i18n.adoc[internationalization].
-
== See also
This attribute can also be specified for:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/navigable.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/navigable.adoc
index 7dcd2dc..db2171d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/navigable.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/navigable.adoc
@@ -7,20 +7,35 @@
The `navigable` attribute allows to specify a domain object's (or view's) navigable parent, as utilized by the 'Where am I' feature.
-For example:
+For example, suppose:
[source,java]
----
@DomainObject
-public class Company { /* ... */ }
+public class Company {
+ // ...
+}
+----
+
+then:
+
+[source,java]
+----
+import lombok.Getter;
+import lombok.Setter;
@DomainObject
public class Employee {
- @Getter @PropertyLayout(navigable=Navigable.PARENT)
- Company myCompany;
+ @PropertyLayout(navigable=Navigable.PARENT)
+ @Getter @Setter
+ private Company myCompany;
+
+ // ...
}
----
+This points up to the ``Employee``'s parent ``Company``.
+
For further details on using a navigable tree-structure, see xref:vw:ROOT:features.adoc#where-am-i[Where am I] in the user guide.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc
index 7793914..b5e1b99 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/promptStyle.adoc
@@ -7,22 +7,28 @@
The `promptStyle` attribute is used to specify whether, when editing a domain object property, the new value for the property is prompted by way of a dialog box, or is prompted using an inline panel (replacing the property on the page).
-If the attribute is not set, then the value of the xref:vw:ROOT:configuration-properties.adoc[configuration property] `isis.viewer.wicket.promptStyle` is used.
+If the attribute is not set, then the value of the xref:refguide:config:sections/isis.viewer.wicket.adoc#isis.viewer.wicket.prompt-style[`isis.viewer.wicket.prompt-style`] configuration property is used.
If this is itself not set, then an inline prompt is used.
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@PropertyLayout(
- promptStyle=PromptStyle.INLINE // <1>
+ promptStyle=PromptStyle.INLINE // <.>
)
- public int getNotes(){ /* ... */ }
- public void setNotes(String notes) { /* ... */ }
+ @Getter @Setter
+ private String notes;
+
+ // ...
}
----
-<1> prompt for the new value for the property using an inline panel
+<.> prompt for the new value for the property using an inline panel
Note that the value `INLINE_AS_IF_EDIT` does not make sense for properties; if specified then it will be interpreted as just `INLINE`.
Alternatively, the `promptStyle()` can be specified using xref:userguide:fun:ui.adoc#object-layout[file-based layouts].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderDay.adoc
similarity index 69%
rename from api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc
rename to api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderDay.adoc
index cd4b83a..9af9512 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderedAsDayBefore.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/renderDay.adoc
@@ -1,17 +1,15 @@
-[#renderedAsDayBefore]
-= `renderedAsDayBefore()`
+[#renderDay]
+= `renderDay()`
: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 [...]
:page-partial:
-
-The `renderedAsDayBefore` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object.
+The `renderDay` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object.
It is ignored for properties of other types.
This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time.
-In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2.
-Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
+In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
@@ -21,26 +19,29 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Tenancy {
- public LocalDate getStartDate() { /* ... */ }
- public void setStartDate(LocalDate startDate) { /* ... */ }
+
+ @Getter @Setter
+ private LocalDate startDate;
+
@PropertyLayout(
- renderedAsDayBefore=true
+ renderDay = RenderDay.AS_DAY_BEFORE
)
- public LocalDate getEndDate() { /* ... */ }
- public void setEndDate(LocalDate EndDate) { /* ... */ }
- ...
+ @Getter @Setter
+ private LocalDate endDate;
+
+ // ...
}
----
-
-
== Alternatives
As an alternative to using the annotation, the dynamic xref:userguide:fun:ui.adoc#object-layout[file-based layout] can be used instead.
-
== See also
-This attribute is also supported for xref:refguide:applib-ant:ParameterLayout.adoc#renderedAsDayBefore[parameters].
+This attribute is also supported for xref:refguide:applib-ant:ParameterLayout.adoc#renderDay[parameters].
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/repainting.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/repainting.adoc
index a05bee8..1f3d92d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/repainting.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/repainting.adoc
@@ -12,7 +12,6 @@ This is primarily for performance, eg can improve the user experience when rende
Note that for this to work, the viewer will also ensure that none of the property's parent component (such as a tab group panel) are re-rendered.
-
[NOTE]
====
Design note: we considered implementing this an "immutable" flag on the xref:refguide:applib-ant:Property.adoc[`@Property`] annotation (because this flag is typically appropriate for immutable/unchanging properties of a domain object).
@@ -23,12 +22,18 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Document {
+
@PropertyLayout(
repainting=Repainting.NO_REPAINT
)
- public Blob getBlob(){ /* ... */ }
- public void setBlob(Blob blob) { /* ... */ }
+ @Getter @Setter
+ private Blob blob;
+
+ // ...
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc
index 23bdd68..97e7228 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/typicalLength.adoc
@@ -17,12 +17,17 @@ For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class Customer {
+
@javax.jdo.annotations.Column(length=30)
@ParameterLayout(typicalLength=20)
- public String getFirstName() { /* ... */ }
- public void setFirstName(String firstName) { /* ... */ }
- ...
+ @Getter @Setter
+ private String firstName;
+
+ // ...
}
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc
index 15ad0be..fbdd8a1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Title.adoc
@@ -1,3 +1,4 @@
+[#Title]
= `@Title`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
index e06674e..463dd2a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel.adoc
@@ -1,10 +1,10 @@
+[#ViewModel]
= `@ViewModel`
: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 - not currently supported, need to reinstate MementoService
-
The `@ViewModel` annotation, applied to a class, indicates that the class is a view model.
It's a synonym for using `@DomainObject(nature=VIEW_MODEL)`.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel/objectType.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel/objectType.adoc
index 4df6395..9d2307f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel/objectType.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/ViewModel/objectType.adoc
@@ -11,14 +11,12 @@ This value is used internally to generate a string representation of an objects
This can appear in several contexts, including:
* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
+(see xref:refguide:applib-svc:BookmarkService.adoc[`BookmarkService`])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
-* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer] (in general and in particular if xref:vw:ROOT:features.adoc#hints-and-copy-url[copying URLs])
+* in the URLs of the xref:vw:ROOT:about.adoc[Wicket viewer]
* in XML snapshots generated by the xref:refguide:applib-svc:XmlSnapshotService.adoc[`XmlSnapshotService`]
-
-
== Examples
For example:
@@ -33,7 +31,6 @@ public class Order {
}
----
-
== Precedence
The rules of precedence are:
@@ -47,7 +44,6 @@ If only `schema` is defined, then the value is "`schema.className`".
4. Fully qualified class name of the entity.
-
[TIP]
====
This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
index 2829efc..fde7bd9 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlJavaTypeAdapter.adoc
@@ -1,3 +1,4 @@
+[#javax-xml-bind-annotation-adapters-XmlJavaTypeAdapter]
= `@XmlJavaTypeAdapter` (`jaxb`)
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
index 48f9833..af5ea26 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/XmlRootElement.adoc
@@ -1,3 +1,4 @@
+[#javax-xml-bind-annotation-adapters-XmlRootElement]
= `@XmlRootElement` (`jaxb`)
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Blob.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Blob.adoc
index 39b5a13..a02ceaa 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Blob.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Blob.adoc
@@ -1,3 +1,4 @@
+[#Blob]
= `Blob`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Clob.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Clob.adoc
index ca3b4bf..65f4f15 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Clob.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/value-types/Clob.adoc
@@ -1,3 +1,4 @@
+[#Clob]
= `Clob`
: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 [...]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc
index b6b3143..15b6a6d 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/choices.adoc
@@ -5,33 +5,37 @@
-The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box. Unlike xref:refguide:applib-cm:methods.adoc#autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
+The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.
+Unlike xref:refguide:applib-cm:methods.adoc#autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
The signature of the supporting method depends on whether it is for an action parameter or a property.
-
== Parameters
For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
[source,java]
----
-public Collection<T> choicesNXxx() { /* ... */ }
+public Collection<T> choicesNXxx() {
+ // ...
+}
----
-
For example:
[source,java]
----
+import lombok.Getter;
+import lombok.Setter;
+
public class ShoppingCartItem {
@Property(editing=Editing.DISABLED)
- public Product getProduct() { /* ... */ }
- public void setProduct(Product product) { /* ... */ }
+ @Getter @Setter
+ private Product product;
@Property(editing=Editing.DISABLED)
- public int getQuantity() { /* ... */ }
- public void setQuantity(int quantity) { /* ... */ }
+ @Getter @Setter
+ private int quantity;
@Action(semantics=SemanticsOf.IDEMPOTENT)
public ShoppingCartItem updateProduct(
@@ -48,52 +52,47 @@ public class ShoppingCartItem {
}
----
-
=== Dependent Choices
Action parameters also support the notion of dependent choices, whereby the list of choices is dependent upon the value of some other argument.
-An example can be found in the http://github.com/apache/isis-app-todoapp[TodoApp], whereby `ToDoItem`s are categorized and then can also be subcategorized:
+For example, consider a todo app whereby ``ToDoItem``s are categorized and then can also be subcategorized:
image::reference-methods/prefixes/choices/dependent.png[width="800px",link="{imagesdir}/reference-methods/prefixes/choices/dependent.png"]
-
-
-This functionality is actually implemented as a xref:userguide:fun:mixins.adoc#contributed-action[contributed action], so the code for this is:
+If implemented as a mixin xref:userguide:fun:mixins.adoc#contributed-action[contributed action], the code would look something like:
[source,java]
----
-@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class UpdateCategoryContributions ... {
+public class ToDoItem {
+
+ @Action(semantics = SemanticsOf.IDEMPOTENT)
@ActionLayout(
describedAs = "Update category and subcategory"
)
- @Action(semantics = SemanticsOf.IDEMPOTENT)
- public Categorized updateCategory(
- final Categorized item, // <1>
- final Category category,
- @Parameter(optionality = Optionality.OPTIONAL)
- final Subcategory subcategory) {
- item.setCategory(category);
- item.setSubcategory(subcategory);
- return item;
+ public class updateCategory {
+ public ToDoItem act(
+ final Category category,
+ @Nullable
+ final Subcategory subcategory) {
+ item.setCategory(category);
+ item.setSubcategory(subcategory);
+ return ToDoItem.this;
+ }
+ public List<Subcategory> choices1UpdateCategory( // <.>
+ final Category category) { // <.>
+ return Subcategory.listFor(category);
+ }
}
- public List<Subcategory> choices2UpdateCategory( // <2>
- final Categorized item, // <3>
- final Category category) { // <4>
- return Subcategory.listFor(category);
- }
- ...
+
}
----
-<1> `ToDoItem` implements `Categorized`
-<2> subcategory is the 2-th argument (0-based)
-<3> the item contributed to
-<4> the category selected
-
+<.> "choices" prefix, Nth param
+<.> the category selected
-Dependent choices are not restricted to enums, however. Going back to the shopping cart example shown above, the choices for the `quantity` parameter could be dependent upon the selected `Product`:
+Dependent choices are not restricted to enums, however.
+Going back to the shopping cart example shown above, the choices for the `quantity` parameter could be dependent upon the selected `Product`:
[source,java]
----
@@ -115,7 +114,6 @@ public class ShoppingCartItem {
----
<1> `productService` is a (fictitous) injected service that knows what the quantity choices should be for any given product
-
== Properties
For a property of type `T`, the signature is:
@@ -125,7 +123,6 @@ For a property of type `T`, the signature is:
public Collection<T> choicesXxx() { /* ... */ }
----
-
For example:
[source,java]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc
index 426ab1d..45c4334 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/methods/prefixes/default.adoc
@@ -59,39 +59,42 @@ public class ShoppingCartItem {
<2> default the 1-th parameter using the current value of the `quantity` property
+If implemented as a mixin xref:userguide:fun:mixins.adoc#contributed-action[contributed action], the code would look something like:
Defaults are also supported (of course) for xref:userguide:fun:mixins.adoc#contributed-action[contributed actions].
For example, here is a contributed action for updating category/subcategory of the http://github.com/apache/isis-app-todoapp[TodoApp]:
[source,java]
----
-@DomainService(nature = NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class UpdateCategoryContributions ... {
+public class ToDoItem {
+
+ @Action(semantics = SemanticsOf.IDEMPOTENT)
@ActionLayout(
describedAs = "Update category and subcategory"
)
- @Action(semantics = SemanticsOf.IDEMPOTENT)
- public Categorized updateCategory(
- final Categorized item, // <1>
- final Category category,
- @Nullable final Subcategory subcategory) {
- item.setCategory(category);
- item.setSubcategory(subcategory);
- return item;
- }
- public Category default1UpdateCategory( // <2>
- final Categorized item) {
- return item != null? item.getCategory(): null;
- }
- public Subcategory default2UpdateCategory( // <3>
- final Categorized item) {
- return item != null? item.getSubcategory(): null;
+ public class updateCategory {
+ public ToDoItem act(
+ final Category category,
+ @Nullable
+ final Subcategory subcategory) {
+ item.setCategory(category);
+ item.setSubcategory(subcategory);
+ return ToDoItem.this;
+ }
+ // ...
+ public Category default1UpdateCategory( // <.>
+ final Categorized item) {
+ return ToDoItem.this.getCategory();
+ }
+ public Subcategory default2UpdateCategory( // <.>
+ final Categorized item) {
+ return ToDoItem.this.getSubcategory();
+ }
}
}
----
-<1> `ToDoItem` implements `Categorized`
-<2> defaults the 1-th parameter using the item's `category` property
-<3> defaults the 2-th parameter using the item's `subcategory` property
+<.> defaults the 0-th parameter using the item's `category` property
+<.> defaults the 1-th parameter using the item's `subcategory` property
=== Dependent Defaults
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java b/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java
index 9108902..6737575 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java
@@ -259,8 +259,7 @@ public interface RepositoryService {
<T> Optional<T> firstMatch(Query<T> query); // <.>
// end::refguide[]
/**
- * As {@link #allInstances(Class, long, long)}, but but returning all instances rather than just those
- * * within the specified range..
+ * Reloads the pojo.
*/
// tag::refguide[]
<T> T refresh(T pojo); // <.>
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc b/persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc
index dd6c4bb..025bbe5 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc
@@ -11,9 +11,6 @@ For service also provides access to the underlying JDO `PersistenceManager` for
The following sections discuss the functionality provided by the service, broken out into categories.
-
-
-
== Executing SQL
You can use the `IsisJdoSupportService` to perform arbitrary SQL SELECTs or UPDATEs:
@@ -29,7 +26,6 @@ public interface IsisJdoSupport {
}
----
-
The `executeSql(...)` method allows arbitrary SQL `SELECT` queries to be submitted:
[source,java]
@@ -39,7 +35,6 @@ List<Map<String, Object>> results = isisJdoSupport.executeSql("select * from cus
The result set is automatically converted into a list of maps, where the map key is the column name.
-
In a similar manner, the `executeUpdate(...)` allows arbitrary SQL ``UPDATE``s to be performed.
[source,java]
@@ -54,13 +49,10 @@ The returned value is the number of rows updated.
As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[type-safe JDO query API], discussed xref:pjdo:ROOT:services/IsisJdoSupport.adoc#type-safe-query-api[below].
====
-
-
-
[#type-safe-jdoql-queries]
== Type-safe JDOQL Queries
-DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO], so that JDOQL queries can be built up and executed using a set of type-safe classes.
+DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO], so that JDOQL queries can be built up and executed using a set of type-safe classes.
The types in question for type safe queries are not the domain entities, but rather are companion "Q..." query classes.
These classes are generated dynamically by an link:https://www.jcp.org/en/jsr/detail?id=269[annotation processor] as a side-effect of compilation, one "Q..." class for each of the xref:refguide:applib-ant:PersistenceCapable.adoc[`@PersistenceCapable`] domain entity in your application.
@@ -89,7 +81,6 @@ public interface IsisJdoSupport {
}
----
-
The `executeQuery(...)` method supports the common case of obtaining a set of objects that meet some criteria, filtered using the provided `BooleanExpression`.
To avoid memory leaks, the returned list is cloned and the underlying query closed.
@@ -121,12 +112,10 @@ public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Categor
You can find the full example of the JDOQL equivalent in the xref:refguide:applib-svc:RepositoryService.adoc[`RepositoryService`]
====
-
The `executeUniqueQuery(...)` method (introduced in `1.15.0`) is similar to `executeQuery(...)`, however expects the query to return at most a single object, which it returns (or `null` if none).
The `newTypesafeQuery(...)` method is a lower-level API that allows a type safe query to be instantiated for most sophisticated querying, eg using group by or order by clauses.
-See the
-DataNucleus link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] for full details of using this.
+See the DataNucleus link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] for full details of using this.
One thing to be aware of is that after the query has been executed, it should be closed, using `query.closeAll()`.
If calling `query.executeList()` we also recommend cloning the resultant list first.
@@ -142,11 +131,10 @@ private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
}
----
-
-
== Fixture support
-When writing xref:testing:integtestsupport:about.adoc[integration tests] you'll usually need to tear down some/all mutable transactional data before each test. One way to do that is to use the `executeUpdate(...)` method described xref:pjdo:ROOT:services/IsisJdoSupport.adoc#executing-sql[above].
+When writing xref:testing:integtestsupport:about.adoc[integration tests] you'll usually need to tear down some/all mutable transactional data before each test.
+One way to do that is to use the `executeUpdate(...)` method described xref:pjdo:ROOT:services/IsisJdoSupport.adoc#executing-sql[above].
Alternatively, the `deleteAll(...)` method will let your test delete all instances of a class without resorting to SQL:
@@ -181,9 +169,6 @@ JDO/DataNucleus seems to bump up the version of the object prior to its deletion
Therefore to prevent this from happening (ie to _force_ the deletion of all instances), concurrency checking is temporarily disabled while this method is performed.
====
-
-
-
== Reloading entities
An link:http://www.datanucleus.org:15080/products/accessplatform_5_0/jdo/mapping.html#one_many_relations[(intentional) limitation] of JDO/DataNucleus is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
@@ -191,58 +176,19 @@ An link:http://www.datanucleus.org:15080/products/accessplatform_5_0/jdo/mapping
[source,java]
----
public interface IsisJdoSupport {
- @Programmatic
<T> T refresh(T domainObject);
- @Programmatic
void ensureLoaded(Collection<?> collectionOfDomainObjects);
...
}
----
-
-
-The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object). Under the covers it uses the JDO `PersistenceManager#refresh(...)` API.
-
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class OrderContributions {
- public Order newOrder(final Customer customer) {
- Order order = new Order(customer);
- repositoryService.persistAndFlush(customer); // <1>
- isisJdoSupport.refresh(customer); // <2>
- return order;
- }
- @Inject
- RepositoryService repositoryService;
- @Inject
- IsisJdoSupport isisJdoSupport;
-}
-----
-<1> flush to database, ensuring that the database row corresponding to the `Order` exists in its `order` table.
-<2> reload the parent (customer) from the database, so that its collection of ``Order``s is accurate.
-
-
-[NOTE]
-====
-The particular example that led to this method being added was a 1:m bidirectional relationship, analogous to `Customer 1<-->* Order`.
-Persisting the child `Order` object did not cause the parent ``Customer``'s collection of orders to be updated.
-In fact, JDO does not make any such guarantee to do so.
-Options are therefore either to maintain the collection in code, or to refresh the parent.
-====
-
+The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object).
+Under the covers it uses the JDO `PersistenceManager#refresh(...)` API.
The `ensureLoaded(...)` method allows a collection of domain objects to be loaded from the database in a single hit.
This can be valuable as a performance optimization to avoid multiple roundtrips to the database.
Under the covers it uses the `PersistenceManager#retrieveAll(...)` API.
-
-
-
-
== JDO `PersistenceManager`
The functionality provided by `IsisJdoSupport` focus only on the most common use cases.
@@ -276,7 +222,4 @@ public class Orders {
}
----
-
-
-
TODO: v2: IsisJdoSupport_v3_2
diff --git a/security/shiro/src/main/adoc/modules/shiro/pages/about/run-as.adoc b/security/shiro/src/main/adoc/modules/shiro/pages/about/run-as.adoc
index 9a3828b..3e3b014 100644
--- a/security/shiro/src/main/adoc/modules/shiro/pages/about/run-as.adoc
+++ b/security/shiro/src/main/adoc/modules/shiro/pages/about/run-as.adoc
@@ -60,7 +60,7 @@ This could be exposed in the UI using a simple `RunAsService`, for example:
[source,java]
----
-@DomainService(nature = NatureOfService.VIEW_MENU_ONLY)
+@DomainService(nature = NatureOfService.VIEW)
@DomainServiceLayout(menuBar = DomainServiceLayout.MenuBar.TERTIARY)
public class RunAsService {
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/features/blob-attachments.adoc b/viewers/wicket/adoc/modules/ROOT/pages/features/blob-attachments.adoc
index 6c8944f..40e2f09 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/features/blob-attachments.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/features/blob-attachments.adoc
@@ -5,7 +5,7 @@
-The Apache Isis application library provides the xref:refguide:applib-cm:classes/value-types.adoc#blob[Blob] value type (binary large objects) and also the xref:refguide:applib-cm:classes/value-types.adoc#clob[Clob]
+The Apache Isis application library provides the xref:refguide:applib-cm:classes/value-types.adoc#Blob[Blob] value type (binary large objects) and also the xref:refguide:applib-cm:classes/value-types.adoc#Clob[Clob]
value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).
A class can define a property using either of these types, for example: