[isis] branch master updated: ISIS-2507: add javadoc for DomainObjectList

[ah...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git


The following commit(s) were added to refs/heads/master by this push:
     new 11e147b  ISIS-2507: add javadoc for DomainObjectList
11e147b is described below

commit 11e147bb4d808208b8e8ae121070e11c876b4bcf
Author: Andi Huber <ah...@apache.org>
AuthorDate: Fri Jan 29 09:52:49 2021 +0100

    ISIS-2507: add javadoc for DomainObjectList
---
 .../org/apache/isis/applib/domain/DomainObjectList.java   | 15 +++++++++++++++
 .../org/apache/isis/applib/services/jaxb/JaxbService.java |  7 +++++++
 .../core/runtimeservices/jaxb/JaxbServiceDefault.java     |  8 +++++---
 3 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/api/applib/src/main/java/org/apache/isis/applib/domain/DomainObjectList.java b/api/applib/src/main/java/org/apache/isis/applib/domain/DomainObjectList.java
index 9e47e99..2f345aa 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/domain/DomainObjectList.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/domain/DomainObjectList.java
@@ -37,6 +37,21 @@ import org.apache.isis.applib.annotation.Optionality;
 import org.apache.isis.applib.annotation.Property;
 import org.apache.isis.applib.jaxb.PersistentEntitiesAdapter;
 
+/**
+ * The initial idea of {@link DomainObjectList} was to simplify restful clients.
+ * <p>
+ * In the original Restful Objects specification, invoking an action that returned 
+ * a list meant that the RO client needed to handle this collection, which didn't 
+ * have any identity. That made for special case logic in the client.  
+ * <p>
+ * Instead, if the RO client invokes the action but uses the <i>Accept Header</i> to 
+ * request an object, then the RO viewer would automatically wrap the returned list 
+ * in this {@link DomainObjectList} view model.
+ * <p>
+ * Thus, the RO client then only ever needs to know how to render an object, in all cases.
+ *  
+ * @since 1.x {@index}
+ */
 @XmlRootElement(name = "list")
 @XmlType(
         propOrder = {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java b/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
index c986544..9c3d189 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
@@ -31,6 +31,8 @@ import javax.xml.bind.Unmarshaller;
 import org.apache.isis.applib.mixins.dto.Dto_downloadXsd;
 import org.apache.isis.commons.internal.base._Casts;
 import org.apache.isis.commons.internal.base._NullSafe;
+import org.apache.isis.commons.internal.debug._Probe;
+import org.apache.isis.commons.internal.exceptions._Exceptions;
 import org.apache.isis.commons.internal.resources._Xml;
 
 import lombok.NonNull;
@@ -210,6 +212,11 @@ public interface JaxbService {
                 unmarshaller.setProperty(entry.getKey(), entry.getValue());
             }
             
+            if(xml.contains("<actionOwningType>isis.applib.ConfigurationMenu</actionOwningType>")) {
+                _Probe.errOut("+++++++++++\n\n %s", xml);
+                _Exceptions.dumpStackTrace();
+            }
+            
             configure(unmarshaller);
 
             val pojo = unmarshaller.unmarshal(new StringReader(xml));
diff --git a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/jaxb/JaxbServiceDefault.java b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/jaxb/JaxbServiceDefault.java
index 09e304b..5f8d836 100644
--- a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/jaxb/JaxbServiceDefault.java
+++ b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/jaxb/JaxbServiceDefault.java
@@ -83,8 +83,10 @@ public class JaxbServiceDefault extends JaxbService.Simple {
     }
 
     @Override
-    protected Object internalFromXml(@NonNull JAXBContext jaxbContext, String xml,
-            Map<String, Object> unmarshallerProperties) throws JAXBException {
+    protected Object internalFromXml(
+            final @NonNull JAXBContext jaxbContext, 
+            final String xml,
+            final Map<String, Object> unmarshallerProperties) throws JAXBException {
      
         val pojo = super.internalFromXml(jaxbContext, xml, unmarshallerProperties);
         if(pojo instanceof DomainObjectList) {
@@ -97,7 +99,7 @@ public class JaxbServiceDefault extends JaxbService.Simple {
         }
         return pojo;
     }
-
+    
     @Override
     protected void configure(final Unmarshaller unmarshaller) {
         unmarshaller.setAdapter(PersistentEntityAdapter.class,