Update NationalIdService and tests

src/main/java/com/persiantools4j/collection/hometown/Hometown.java

@@ -24,47 +24,38 @@
 import java.util.Objects;
 
 /**
- * Represents a {@code Hometown}, encapsulating its code(s), province, and city.
+ * Represents a {@code Hometown}, encapsulating its province, city and code(s).
  * <p>
  * This class is immutable and should be instantiated using the static factory method.
  */
 @Generated
 public final class Hometown {
 
-    private final List<String> code;
     private final String province;
     private final String city;
+    private final List<String> codes;
 
     /**
      * Constructs an immutable {@code Hometown} instance.
      * <p>
      * This constructor is annotated with {@link JsonCreator} to enable Jackson deserialization,
      * mapping the specified JSON properties to the corresponding fields.
      *
-     * @param city     the name of the city, mapped from the {@code "city"} JSON property
      * @param province the name of the province where the city is located,
      *                 mapped from the {@code "province"} JSON property
-     * @param code     a list of code(s) associated with the {@code Hometown},
+     * @param city     the name of the city, mapped from the {@code "city"} JSON property
+     * @param codes    a list of code(s) associated with the {@code Hometown},
      *                 mapped from the {@code "code"} JSON property
      */
     @JsonCreator
     public Hometown(
-            @JsonProperty("city") String city,
             @JsonProperty("province") String province,
-            @JsonProperty("code") List<String> code
+            @JsonProperty("city") String city,
+            @JsonProperty("code") List<String> codes
     ) {
-        this.city = city;
         this.province = province;
-        this.code = code;
-    }
-
-    /**
-     * Returns the list of code(s) associated with this {@code Hometown}.
-     *
-     * @return the list of code(s)
-     */
-    public List<String> getCode() {
-        return code;
+        this.city = city;
+        this.codes = codes;
     }
 
     /**
@@ -85,10 +76,19 @@ public String getCity() {
         return city;
     }
 
+    /**
+     * Returns the list of code(s) associated with this {@code Hometown}.
+     *
+     * @return the list of code(s)
+     */
+    public List<String> getCodes() {
+        return codes;
+    }
+
     /**
      * Compares this {@code Hometown} instance with the specified object for equality.
      * <p>
-     * Two {@code Hometown} objects are considered equal if they have the same code(s), province, and city.
+     * Two {@code Hometown} objects are considered equal if they have the same province, city and code(s).
      *
      * @param o the object to compare with
      * @return {@code true} if the specified object is equal to this {@code Hometown}, otherwise {@code false}
@@ -102,33 +102,33 @@ public boolean equals(Object o) {
             return false;
         }
         Hometown hometown = (Hometown) o;
-        return Objects.equals(code, hometown.code)
-                && Objects.equals(province, hometown.province)
-                && Objects.equals(city, hometown.city);
+        return Objects.equals(province, hometown.province)
+                && Objects.equals(city, hometown.city)
+                && Objects.equals(codes, hometown.codes);
     }
 
     /**
      * Returns a hash code value for this {@code Hometown} instance.
      * <p>
-     * The hash code is generated based on the code(s), province and city names.
+     * The hash code is generated based on the province, city and code(s).
      *
      * @return a hash code value for this {@code Hometown} instance
      */
     @Override
     public int hashCode() {
-        return Objects.hash(code, province, city);
+        return Objects.hash(province, city, codes);
     }
 
     /**
      * Returns a string representation of this {@code Hometown} instance.
      * <p>
-     * The string representation includes the code(s), province, and city names.
+     * The string representation includes the province, city, and code(s).
      *
      * @return a string representation of the {@code Hometown} object
      */
     @Override
     public String toString() {
-        return "Hometown{" + "code=" + code + ", province='" + province + '\'' + ", city='" + city + '\'' + '}';
+        return "Hometown{" + "province='" + province + '\'' + ", city='" + city + '\'' + ", codes=" + codes + '}';
     }
 
 }

src/main/java/com/persiantools4j/module/nationalid/NationalId.java

@@ -30,18 +30,26 @@
 public final class NationalId {
 
     private final String id;
-    private String hometownCode;
-    private String personalCode;
-    private int controlDigit;
-    private List<Hometown> hometownList;
+    private final String hometownCode;
+    private final String personalCode;
+    private final int controlDigit;
+    private final List<Hometown> hometowns;
 
     /**
-     * Constructs a new {@code NationalId} instance with the specified national ID string.
+     * Constructs a new {@code NationalId} instance with the specified details.
      *
-     * @param nationalId the national ID string
+     * @param id           the national ID string
+     * @param hometownCode the code representing the associated hometown
+     * @param personalCode the personal code extracted from the national ID
+     * @param controlDigit the control digit used for validation
+     * @param hometowns    a list of {@link Hometown} instances associated with the hometown code
      */
-    public NationalId(String nationalId) {
-        this.id = nationalId;
+    NationalId(String id, String hometownCode, String personalCode, int controlDigit, List<Hometown> hometowns) {
+        this.id = id;
+        this.hometownCode = hometownCode;
+        this.personalCode = personalCode;
+        this.controlDigit = controlDigit;
+        this.hometowns = hometowns;
     }
 
     /**
@@ -62,15 +70,6 @@ public String getHometownCode() {
         return hometownCode;
     }
 
-    /**
-     * Sets the hometown code for this national ID.
-     *
-     * @param hometownCode the new hometown code
-     */
-    public void setHometownCode(String hometownCode) {
-        this.hometownCode = hometownCode;
-    }
-
     /**
      * Gets the personal code segment within the national ID.
      *
@@ -80,15 +79,6 @@ public String getPersonalCode() {
         return personalCode;
     }
 
-    /**
-     * Sets the personal code for this national ID.
-     *
-     * @param personalCode the new personal code
-     */
-    public void setPersonalCode(String personalCode) {
-        this.personalCode = personalCode;
-    }
-
     /**
      * Retrieves the control digit used in the national ID.
      *
@@ -98,31 +88,13 @@ public int getControlDigit() {
         return controlDigit;
     }
 
-    /**
-     * Sets the control digit for this national ID.
-     *
-     * @param controlDigit the new control digit
-     */
-    public void setControlDigit(int controlDigit) {
-        this.controlDigit = controlDigit;
-    }
-
     /**
      * Retrieves the list of hometowns associated with this national ID.
      *
      * @return a {@link List} of {@link Hometown} instances
      */
-    public List<Hometown> getHometownList() {
-        return hometownList;
-    }
-
-    /**
-     * Sets the list of {@link Hometown}s for this national ID.
-     *
-     * @param hometownList the new {@link List} of {@link Hometown}
-     */
-    public void setHometownList(List<Hometown> hometownList) {
-        this.hometownList = hometownList;
+    public List<Hometown> getHometowns() {
+        return hometowns;
     }
 
     /**
@@ -169,7 +141,7 @@ public int hashCode() {
     public String toString() {
         return "NationalId{" + "id='" + id + '\'' + ", hometownCode='" + hometownCode + '\'' +
                 ", personalCode='" + personalCode + '\'' + ", controlDigit=" + controlDigit +
-                ", hometownList=" + hometownList + '}';
+                ", hometowns=" + hometowns + '}';
     }
 
 }

src/main/java/com/persiantools4j/module/nationalid/NationalIdService.java

@@ -119,23 +119,20 @@ public List<Hometown> findHometown(String nationalId) {
         validate(finalNationalId);
         String firstThreeDigits = finalNationalId.substring(0, 3);
         return HometownCollection.getInstance()
-                .findAllBy(hometown -> hometown.getCode().contains(firstThreeDigits));
+                .findAllBy(hometown -> hometown.getCodes().contains(firstThreeDigits));
     }
 
     @Override
     public NationalId parse(String nationalId) {
         String finalNationalId = normalize(nationalId);
-        List<Hometown> hometownList = findHometown(finalNationalId);
-        if (hometownList.isEmpty()) {
+        List<Hometown> hometowns = findHometown(finalNationalId);
+        if (hometowns.isEmpty()) {
             throw new ParseException("Unable to find hometown associated to the national ID: " + finalNationalId);
         }
-        String controlDigit = finalNationalId.substring(9);
-        NationalId nationalIdObj = new NationalId(finalNationalId);
-        nationalIdObj.setHometownCode(finalNationalId.substring(0, 3));
-        nationalIdObj.setPersonalCode(finalNationalId.substring(3, finalNationalId.length() - 1));
-        nationalIdObj.setControlDigit(Integer.parseInt(controlDigit));
-        nationalIdObj.setHometownList(hometownList);
-        return nationalIdObj;
+        String hometownCode = finalNationalId.substring(0, 3);
+        String personalCode = finalNationalId.substring(3, finalNationalId.length() - 1);
+        int controlDigit = Integer.parseInt(finalNationalId.substring(9));
+        return new NationalId(finalNationalId, hometownCode, personalCode, controlDigit, hometowns);
     }
 
 }

src/test/java/com/persiantools4j/collection/hometown/HometownCollectionTest.java

@@ -42,14 +42,14 @@ protected Collection<Hometown> getTestCollectionInstance() {
     @Test
     @DisplayName("Get populated collection")
     void populatedHometownListTest() {
-        Hometown expectedHometown = new Hometown("تهران مرکزی", "تهران",
+        Hometown expectedHometown = new Hometown("تهران", "تهران مرکزی",
                 Arrays.asList("001", "002", "003", "004", "005", "006", "007", "008"));
         assertThat(getTestCollectionInstance().findAllBy(hometown -> true))
                 .isNotNull()
                 .isNotEmpty()
                 .contains(expectedHometown)
                 .allSatisfy(hometown -> {
-                    assertThat(hometown.getCode())
+                    assertThat(hometown.getCodes())
                             .isNotNull()
                             .isNotEmpty()
                             .allMatch(code -> code.matches("\\d{3}"));

src/test/java/com/persiantools4j/module/nationalid/NationalIdServiceTest.java

@@ -135,9 +135,9 @@ private static Stream<Arguments> invalidCases() {
     @BeforeAll
     static void beforeAll() {
         nationalIdService = new NationalIdService();
-        expectedHometown = new Hometown("خوی", "آذربایجان غربی", Arrays.asList("279", "280"));
+        expectedHometown = new Hometown("آذربایجان غربی", "خوی", Arrays.asList("279", "280"));
         hometownPredicate = hometown -> !StringUtils.isBlank(hometown.getProvince())
-                && !StringUtils.isBlank(hometown.getCity()) && !hometown.getCode().isEmpty();
+                && !StringUtils.isBlank(hometown.getCity()) && !hometown.getCodes().isEmpty();
     }
 
     @Nested
@@ -315,7 +315,7 @@ void parseWithValidNationalIdTest(String nationalId) {
             assertThat(actualNationalId.getPersonalCode())
                     .isNotBlank()
                     .hasSize(6);
-            assertThat(actualNationalId.getHometownList())
+            assertThat(actualNationalId.getHometowns())
                     .isNotNull()
                     .isNotEmpty()
                     .allMatch(hometownPredicate);
@@ -330,7 +330,7 @@ void parseWithSingleValidNationalIdTest() {
             assertThat(actualNationalId.getHometownCode()).isEqualTo("279");
             assertThat(actualNationalId.getPersonalCode()).isEqualTo("156789");
             assertThat(actualNationalId.getControlDigit()).isEqualTo(5);
-            assertThat(actualNationalId.getHometownList())
+            assertThat(actualNationalId.getHometowns())
                     .isNotNull()
                     .hasSize(1)
                     .containsOnly(expectedHometown);