This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-2485 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 11ef3ac2934f58d2bb731281823e184dbf8f7393 Author: danhaywood <[email protected]> AuthorDate: Wed Apr 12 07:15:05 2023 +0100 CAUSEWAY-2485: tidies up @Action#typeOf --- .../dom/domain/actions/Action/ActionMenu.java | 9 ++--- .../ActionChoicesFromPage-description.adoc | 2 ++ .../ActionDomainEventPage-description.adoc | 3 ++ .../ActionSemanticsIdempotentMetaAnnotation.java | 40 --------------------- .../typeOf/ActionTypeOfPage-description.adoc | 41 +++++++++++++++------- .../actions/Action/typeOf/ActionTypeOfPage.java | 40 +++++++++------------ .../Action/typeOf/ActionTypeOfPage.layout.xml | 8 +++-- ...n.adoc => ActionTypeOfChildVm-description.adoc} | 2 +- ...m.layout.xml => ActionTypeOfChildVm.layout.xml} | 1 - ...ainObjectXxxLifecycleEventPage-description.adoc | 2 ++ 10 files changed, 60 insertions(+), 88 deletions(-) diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/ActionMenu.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/ActionMenu.java index 9a9a983368..2b4fba1aa0 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/ActionMenu.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/ActionMenu.java @@ -89,14 +89,11 @@ public class ActionMenu { @Action(semantics = SemanticsOf.SAFE) @ActionLayout(cssClassFa="fa-shapes", describedAs = "Semantic relationship between actions and other properties or collections") public ActionTypeOfPage typeOf(){ - val typeOfVm = new ActionTypeOfPage(); - val children = typeOfVm.getChildren(); - - // add to either one collection or the other + val page = new ActionTypeOfPage(); samples.stream() .map(ActionTypeOfChildVm::new) - .forEach(children::add); - return typeOfVm; + .forEach(e -> page.getChildren().add(e)); + return page; } diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/choicesFrom/ActionChoicesFromPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/choicesFrom/ActionChoicesFromPage-description.adoc index 1893d1937d..9a814cde61 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/choicesFrom/ActionChoicesFromPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/choicesFrom/ActionChoicesFromPage-description.adoc @@ -1,5 +1,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 [...] +CAUTION: this feature is currently broken in the demo (though it will work in most apps); see link:https://issues.apache.org/jira/browse/CAUSEWAY-3418[CAUSEWAY-3418]. + Actions parameters can be either value types or reference types (typically entities), and can be either for single-valued (a scalar) or multi-valued (a list). Scalar values can be entered directly, but other combinations require a supporting method or other mechanism to provide a list of candidates for the end-user to select: diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage-description.adoc index 7c6d8b547e..2e0bdff256 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage-description.adoc @@ -1,5 +1,8 @@ :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 [...] +CAUTION: the "executing" and "executed" domain events are currently not emitted for mixin actions; see link:https://issues.apache.org/jira/browse/CAUSEWAY-3409[CAUSEWAY-3409]. + + Usually a domain event is emitted by the framework to emit whenever the user interacts with an action. Domain service subscribers can influence this interaction, either by: diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsIdempotentMetaAnnotation.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsIdempotentMetaAnnotation.java deleted file mode 100644 index f57c6cc15e..0000000000 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsIdempotentMetaAnnotation.java +++ /dev/null @@ -1,40 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ -package demoapp.dom.domain.actions.Action.semantics; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Inherited; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -import org.apache.causeway.applib.annotation.Action; -import org.apache.causeway.applib.annotation.SemanticsOf; - -//tag::class[] -@Action(semantics = SemanticsOf.IDEMPOTENT) // <.> -@Inherited -@Target({ - ElementType.TYPE, ElementType.METHOD // <.> -}) -@Retention(RetentionPolicy.RUNTIME) -public @interface ActionSemanticsIdempotentMetaAnnotation { - -} -//end::class[] diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc index 2b3adb2b5e..062ef56f50 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc @@ -1,38 +1,53 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -The `typeOf` element indicates the element type for an action that returns a collection. +CAUTION: this feature is currently broken; see link:https://issues.apache.org/jira/browse/CAUSEWAY-3423[CAUSEWAY-3423]. -Normally this can be inferred from the generic type, for example `Customer` within `List<Customer>`. -This annotation offers an alternative syntax. +Actions that return lists of objects are usually parameterized, for example, returning `List<Customer>` or `List<Order>`. +The framework uses the generic parameter to ensure that the list is rendered appropriately for that element type. -CAUTION: this annotation may be deprecated in the future. +In some rare scenarios though it may be necessary to return only a raw (non-parameterized) `List`. +In these cases the link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Action.html#typeof[@Action#typeOf] element can be used to indicate the element type of the returned `List`. -// TODO: I have a suspicion that there is a genuine use case for this annotation ... but need to dig deeper. +=== How this demo works -== Example - -The demo object defines a `children` collection: +This page object defines a `children` collection: [source,java] ---- include::ActionTypeOfPage.java[tags=class-collections-children] ---- -The `find` action returns a standalone collection for a subset of these child objects matching the specified value: +It also defines three variants of a "find" action, which all do the same thing: return those objects whose name matches. +* the `find` action uses a generic parameter list: ++ [source,java,indent=0] ---- -include::ActionTypeOfPage.java[tags=action] +include::ActionTypeOfPage.java[tags=action-returning-generic-list] ---- <.> indicates the type of element in the returned list -<.> action defines a raw list ++ +The standalone list returned shows columns for the properties of the element type. -That said, the `findButWithNoAnnotation` action has identical behaviour, even without the `typeOf` element: +* the `findReturningRawList` action has the same functionality, but is defined to return a raw list: ++ +[source,java,indent=0] +---- +include::ActionTypeOfPage.java[tags=action-returning-raw-list] +---- +<.> action defines a raw list ++ +Because this action effectively is returning only a `List<Object>`, the resultant table shows only icons for the matching elements; there are no columns shown for its properties. +* finally the `findReturningRawListButAnnotated` action also return a raw list, but is also annotated using `@Action#typeOf`: ++ [source,java,indent=0] ---- -include::ActionTypeOfPage.java[tags=action-no-annotation] +include::ActionTypeOfPage.java[tags=action-returning-raw-list-but-annotated] ---- +<.> indicates the type of element in the returned list <.> action defines a raw list ++ +The standalone list returned by this object should show the full details of the child object. diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.java index 65da5f5646..6b88d0a47f 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.java +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.java @@ -29,7 +29,6 @@ import javax.xml.bind.annotation.XmlRootElement; import javax.xml.bind.annotation.XmlType; import org.apache.causeway.applib.annotation.Action; -import org.apache.causeway.applib.annotation.ActionLayout; import org.apache.causeway.applib.annotation.Collection; import org.apache.causeway.applib.annotation.CollectionLayout; import org.apache.causeway.applib.annotation.DomainObject; @@ -67,38 +66,31 @@ public class ActionTypeOfPage implements HasAsciiDocDescription { // ... //end::class-collections-children[] -//tag::action[] - @Action( - semantics = SemanticsOf.SAFE - , typeOf = ActionTypeOfChildVm.class // <.> - , choicesFrom = "children" - ) - @ActionLayout( - describedAs = - "@Action(typeOf = ActionTypeOfChildVm.class)" - , sequence = "1" - ) - public List find(final String value) { // <.> +//tag::action-returning-generic-list[] + @Action(semantics = SemanticsOf.SAFE) + public List<ActionTypeOfChildVm> find(final String value) { // <.> return getChildren().stream() .filter(x -> x.getValue().contains(value)) .collect(Collectors.toList()); } -//end::action[] +//end::action-returning-generic-list[] -//tag::action-no-annotation[] +//tag::action-returning-raw-list[] + @Action(semantics = SemanticsOf.SAFE) + public List findReturningRawList(final String value) { // <.> + return find(value); + } +//end::action-returning-raw-list[] + +//tag::action-returning-raw-list-but-annotated[] @Action( - semantics = SemanticsOf.SAFE - , choicesFrom = "children" - ) - @ActionLayout( - describedAs = - "@Action()" - , sequence = "2" + semantics = SemanticsOf.SAFE, + typeOf = ActionTypeOfChildVm.class // <.> ) - public List findButNoTypeOfAnnotation(final String value) { // <.> + public List findReturningRawListButAnnotated(final String value) { // <.> return find(value); } -//end::action-no-annotation[] +//end::action-returning-raw-list-but-annotated[] //tag::class-collections-children[] diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.layout.xml b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.layout.xml index d9d84a31d8..2c1ac65ab3 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.layout.xml +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage.layout.xml @@ -35,9 +35,11 @@ </bs3:row> <bs3:row> <bs3:col span="12"> - <cpt:collection id="children"/> - <cpt:collection id="favorites"/> - <cpt:collection id="mixinChildren"/> + <cpt:collection id="children"> + <cpt:action id="find"/> + <cpt:action id="findReturningRawList"/> + <cpt:action id="findReturningRawListButAnnotated"/> + </cpt:collection> </bs3:col> </bs3:row> </bs3:col> diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfVm-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfChildVm-description.adoc similarity index 94% rename from examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfVm-description.adoc rename to examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfChildVm-description.adoc index 45eb91793a..00adaf7634 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfVm-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfChildVm-description.adoc @@ -1,3 +1,3 @@ :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 [...] -This child object exists just to act as the element of the collections of the `ActionTypeOfVm` demo object. +This child object exists just to act as the element of the collections of the `ActionTypeOfPage` demo object. diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfVm.layout.xml b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfChildVm.layout.xml similarity index 98% rename from examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfVm.layout.xml rename to examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfChildVm.layout.xml index 257580e0f5..2441ccf9e7 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfVm.layout.xml +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/child/ActionTypeOfChildVm.layout.xml @@ -19,7 +19,6 @@ <bs3:row> <bs3:col span="10" unreferencedActions="true"> <cpt:domainObject /> - <cpt:action id="returnsStandaloneList"/> </bs3:col> <bs3:col span="2"> <cpt:fieldSet name="" id="sources" /> diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/xxxLifecycleEvent/DomainObjectXxxLifecycleEventPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/xxxLifecycleEvent/DomainObjectXxxLifecycleEventPage-description.adoc index 2490edf19c..12ed556805 100644 --- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/xxxLifecycleEvent/DomainObjectXxxLifecycleEventPage-description.adoc +++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/xxxLifecycleEvent/DomainObjectXxxLifecycleEventPage-description.adoc @@ -8,6 +8,8 @@ However, using link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/i * link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/DomainObject.html#createdlifecycleevent[@DomainObject#createdLifecycleEvent] - when an entity is instantiated in memory (but not yet persisted). Must be a subclass of https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/events/lifecycle/ObjectCreatedEvent[ObjectCreatedEvent]. ++ +CAUTION: the "created" lifecycle event is currently not emitted; see link:https://issues.apache.org/jira/browse/CAUSEWAY-3408[CAUSEWAY-3408]. * link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/DomainObject.html#persistinglifecycleevent[@DomainObject#persistingLifecycleEvent] - when a newly instantiated entity is about to be INSERTed for the first time to the database. Must be a subclass of https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/events/lifecycle/ObjectPersistingEvent[ObjectPersistingEvent].
