Merge branch 'develop'

common/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>magda</artifactId>
         <groupId>be.vlaanderen.vip.mock</groupId>
-        <version>2.16.0</version>
+        <version>2.17.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

interfaces/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <artifactId>magda</artifactId>
     <groupId>be.vlaanderen.vip.mock</groupId>
-    <version>2.16.0</version>
+    <version>2.17.0</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
 

interfaces/src/main/java/be/vlaanderen/vip/magda/client/diensten/GeefSociaalStatuutRequest.java

@@ -6,10 +6,12 @@
 import be.vlaanderen.vip.magda.client.domeinservice.MagdaRegistrationInfo;
 import jakarta.annotation.Nullable;
 import jakarta.validation.constraints.NotNull;
+import lombok.AccessLevel;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.ToString;
 
+import java.time.LocalDate;
 import java.time.OffsetDateTime;
 import java.time.format.DateTimeFormatter;
 
@@ -18,9 +20,12 @@
  * Adds the following fields to the {@link PersonMagdaRequest}:
  * <ul>
  * <li>socialStatusName: the name of the type of social status about which the information is requested</li>
- * <li>date: the date on which the information on the social status was in effect</li>
+ * <li>date: the date on which the information on the social status was in effect.</li>
+ * <li>startDate: required, the start date of the period in which the social status was in effect</li>
+ * <li>endDate: optional, the end date of the period in which the social status was in effect. When not specified, the period is assumed to run until today.</li>
  * <li>locationName: the name of the location where the social status was in effect (optional)</li>
  * </ul>
+ * The "GeefSociaalStatuut" MAGDA service can be queried by a specific date or by period using "startDate" and/or "endDate".
  *
  * @see <a href="file:resources/templates/GeefSociaalStatuut/03.00.0000/template.xml">XML template for this request type</a>
  * @see <a href="https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1243022119/SocZek.GeefSociaalStatuut-03.00">More information on this request type</a>
@@ -31,25 +36,50 @@
 public class GeefSociaalStatuutRequest extends PersonMagdaRequest {
 
     public static class Builder extends PersonMagdaRequest.Builder<Builder> {
+        @Getter(AccessLevel.PROTECTED)
         private String socialStatusName;
-        private OffsetDateTime date;
+        @Getter(AccessLevel.PROTECTED)
+        private LocalDate date;
+        @Getter(AccessLevel.PROTECTED)
+        private LocalDate startDate;
+        @Getter(AccessLevel.PROTECTED)
+        private LocalDate endDate;
+        @Getter(AccessLevel.PROTECTED)
         private String locationName;
 
         public Builder socialStatusName(String socialStatusName) {
             this.socialStatusName = socialStatusName;
             return this;
         }
 
-        public Builder date(OffsetDateTime date) {
+        public Builder date(LocalDate date) {
             this.date = date;
             return this;
         }
 
+        public Builder startDate(LocalDate date) {
+            this.startDate = date;
+            return this;
+        }
+
+        public Builder endDate(LocalDate date) {
+            this.endDate = date;
+            return this;
+        }
+
         public Builder locationName(String locationName) {
             this.locationName = locationName;
             return this;
         }
 
+        /**
+         * @deprecated data type OffsetDateTime has been replaced by LocalDate.
+         */
+        @Deprecated(forRemoval=true)
+        public Builder date(OffsetDateTime date) {
+            return date(date.toLocalDate());
+        }
+
         /**
          * @deprecated method has been renamed to 'socialStatusName'
          */
@@ -69,13 +99,16 @@ public Builder datum(OffsetDateTime date) {
         public GeefSociaalStatuutRequest build() {
             if(getInsz() == null) { throw new IllegalStateException("INSZ number must be given"); }
             if(socialStatusName == null) { throw new IllegalStateException("socialStatusName must be given"); }
-            if(date == null) { throw new IllegalStateException("datum must be given"); }
+            if((date == null && startDate == null) || (date != null && startDate != null)) { throw new IllegalStateException("Either date or startDate must be given"); }
+            if(startDate == null && endDate != null) { throw new IllegalStateException("endDate cannot be given without startDate"); }
 
             return new GeefSociaalStatuutRequest(
                     getInsz(),
                     getRegistration(),
                     socialStatusName,
                     date,
+                    startDate,
+                    endDate,
                     locationName
             );
         }
@@ -84,20 +117,31 @@ public GeefSociaalStatuutRequest build() {
     public static Builder builder() {
         return new Builder();
     }
-
+
+    @NotNull
     private final String socialStatusName;
-    private final OffsetDateTime date;
+    @Nullable
+    private final LocalDate date;
+    @Nullable
+    private final LocalDate startDate;
+    @Nullable
+    private final LocalDate endDate;
+    @Nullable
     private final String locationName;
 
     protected GeefSociaalStatuutRequest(
             @NotNull INSZNumber insz,
             @NotNull String registration,
             @NotNull String socialStatusName,
-            @NotNull OffsetDateTime date,
+            @Nullable LocalDate date,
+            @Nullable LocalDate startDate,
+            @Nullable LocalDate endDate,
             @Nullable String locationName) {
         super(insz, registration);
         this.socialStatusName = socialStatusName;
         this.date = date;
+        this.startDate = startDate;
+        this.endDate = endDate;
         this.locationName = locationName;
     }
 
@@ -111,11 +155,27 @@ protected void fillIn(MagdaDocument request, MagdaRegistrationInfo magdaRegistra
         fillInCommonFields(request, magdaRegistrationInfo);
 
         request.setValue("//SociaalStatuut/Naam", getSocialStatusName());
-        request.setValue("//SociaalStatuut/Datum/Datum", DateTimeFormatter.ISO_LOCAL_DATE.format(getDate()));
-        request.removeNode("//SociaalStatuut/Locatie");
+        if(getDate() != null){
+            request.setValue("//SociaalStatuut/Datum/Datum", DateTimeFormatter.ISO_LOCAL_DATE.format(getDate()));
+        } else {
+            request.removeNode("//SociaalStatuut/Datum/Datum");
+        }
+
+        if(getStartDate() != null) {
+            request.setValue("//SociaalStatuut/Datum/Periode/Begindatum", DateTimeFormatter.ISO_LOCAL_DATE.format(getStartDate()));
+            if(getEndDate() != null) {
+                request.setValue("//SociaalStatuut/Datum/Periode/Einddatum", DateTimeFormatter.ISO_LOCAL_DATE.format(getEndDate()));
+            } else {
+                request.removeNode("//SociaalStatuut/Datum/Periode/Einddatum");
+            }
+        } else {
+            request.removeNode("//SociaalStatuut/Datum/Periode");
+        }
+
         if(getLocationName() != null) {
-            request.createNode("//SociaalStatuut", "Locatie");
-            request.createTextNode("//SociaalStatuut/Locatie", "Naam", getLocationName());
+            request.setValue("//SociaalStatuut/Locatie/Naam", getLocationName());
+        } else {
+            request.removeNode("//SociaalStatuut/Locatie");
         }
     }
 }

interfaces/src/main/java/be/vlaanderen/vip/magda/client/domain/giveperson/MagdaResponsePerson.java

@@ -27,6 +27,12 @@ public Optional<RelatedPerson> referencePerson() {
                        .map(NodeRelatedPerson::new);
     }
 
+    @Override
+    public Optional<FamilyMemberPerson> referenceFamilyMember() {
+        return response.getNode("//Persoon/Referentiepersoon")
+                       .map(NodeFamilyMemberPerson::new);
+    }
+
     @Override
     public List<RelatedPerson> familyMembers() {
         return familyMemberNodes().<RelatedPerson>map(NodeRelatedPerson::new)
@@ -80,9 +86,14 @@ public NodeRelatedPerson(Node node) {
 
         @Override
         public String insz() {
+            return inszOptional()
+                    .orElseThrow(() -> new MalformedMagdaResponseException("Magda response document misses an expected 'INSZ' node"));
+        }
+
+        @Override
+        public Optional<String> inszOptional() {
             return node.get("INSZ")
-                       .flatMap(Node::getValue)
-                       .orElseThrow(() -> new MalformedMagdaResponseException("Magda response document misses an expected 'INSZ' node"));
+                    .flatMap(Node::getValue);
         }
 
         @Override
@@ -135,6 +146,27 @@ public Address mainResidence() {
         }
     }
 
+    private static class NodeFamilyMemberPerson extends NodeRelatedPerson implements FamilyMemberPerson {
+
+        public NodeFamilyMemberPerson(Node node) {
+            super(node);
+        }
+
+        @Override
+        public Optional<LocalDate> startDate() {
+            return node.get("@DatumBegin")
+                    .flatMap(Node::getValue)
+                    .map(LocalDate::parse);
+        }
+
+        @Override
+        public Optional<LocalDate> endDate() {
+            return node.get("@DatumEinde")
+                    .flatMap(Node::getValue)
+                    .map(LocalDate::parse);
+        }
+    }
+
     private record NodeAddress(Node node) implements Address {
 
         @Override

interfaces/src/main/java/be/vlaanderen/vip/magda/client/domain/giveperson/Person.java

@@ -1,5 +1,6 @@
 package be.vlaanderen.vip.magda.client.domain.giveperson;
 
+import be.vlaanderen.vip.magda.MalformedMagdaResponseException;
 import be.vlaanderen.vip.magda.client.domain.dto.INSZ;
 
 import java.time.LocalDate;
@@ -21,6 +22,11 @@ public interface Person {
      */
     Optional<RelatedPerson> referencePerson();
 
+    /**
+     * Information on the reference person (as family member) of the citizen (if any).
+     */
+    Optional<FamilyMemberPerson> referenceFamilyMember();
+
     /**
      * Information on the family members of the citizen.
      */
@@ -44,17 +50,31 @@ interface RelatedPerson {
         /**
          * INSZ number of the person.
          *
+         * @throws MalformedMagdaResponseException if the field is not present.
          * @see INSZ
+         * @deprecated This field is in fact not always present in a well-formed document; use {@link #inszOptional()} as a replacement for this method.
          */
+        @Deprecated
         String insz();
 
+        /**
+         * INSZ number of the person (if any).
+         *
+         * @see INSZ
+         */
+        Optional<String> inszOptional();
+
         /**
          * The first name of the person.
+         *
+         * @return concatenation of the person's first names, or an empty string if the document contains no information on their first names.
          */
         String firstName();
 
         /**
          * The last name of the person.
+         *
+         * @return concatenation of the person's last names, or an empty string if the document contains no information on their last names.
          */
         String lastName();
     }
@@ -66,11 +86,15 @@ interface DetailedRelatedPerson extends RelatedPerson {
 
         /**
          * The person's date of birth.
+         *
+         * @throws java.time.format.DateTimeParseException in case it's an incomplete date.
          */
         LocalDate dateOfBirth();
 
         /**
          * The person's date of death (if any).
+         *
+         * @throws java.time.format.DateTimeParseException in case it's an incomplete date.
          */
         Optional<LocalDate> deathDate();
 
@@ -80,6 +104,28 @@ interface DetailedRelatedPerson extends RelatedPerson {
         Address mainResidence();
     }
 
+    /**
+     * Information on a person's family member.
+     */
+    interface FamilyMemberPerson extends RelatedPerson {
+
+        /**
+         * The date when this related person started being a family member of the person.
+         * This field should in principle always be present, but it's technically possible for it to be missing from a document.
+         *
+         * @throws java.time.format.DateTimeParseException in case it's an incomplete date.
+         */
+        Optional<LocalDate> startDate();
+
+        /**
+         * The date when this related person ceased to be a family member of the person.
+         * If there is no end date, then they're still a family member of the person to this day.
+         *
+         * @throws java.time.format.DateTimeParseException in case it's an incomplete date.
+         */
+        Optional<LocalDate> endDate();
+    }
+
     /**
      * Address information.
      */