Code refactor (#6)

- change class name PeselNumbers to PeselDigits
- remove validation from PeselDigits constructor
to validate and set digits in Pesel constructor
- javadoc changes
- readme.md update

README.md

@@ -1,5 +1,5 @@
 # PESEL
-[![Maven central repository](https://img.shields.io/maven-central/v/io.github.viepovsky/pesel?style=plastic&versionPrefix=2.0.1)](https://central.sonatype.com/artifact/io.github.viepovsky/pesel/2.0.1/overview)
+[![Maven central repository](https://img.shields.io/maven-central/v/io.github.viepovsky/pesel?style=plastic&versionPrefix=2.0.2)](https://central.sonatype.com/artifact/io.github.viepovsky/pesel/2.0.2/overview)
 [![Build and test](https://img.shields.io/github/actions/workflow/status/viepovsky/PESEL/gradle.yml?style=plastic)](https://github.com/viepovsky/PESEL/actions/workflows/gradle.yml)
 [![Codecov coverage](https://img.shields.io/codecov/c/github/viepovsky/PESEL?style=plastic)](https://codecov.io/github/viepovsky/PESEL)
 [![License MIT](https://img.shields.io/github/license/viepovsky/PESEL?style=plastic)](https://github.com/viepovsky/PESEL/blob/master/LICENSE)
@@ -18,14 +18,14 @@ You can read more about PESEL [**here**](https://en.wikipedia.org/wiki/PESEL)
 
 ## Installation
 
-The `PESEL` library is available in the [Maven Central Repository](https://central.sonatype.com/artifact/io.github.viepovsky/pesel/2.0.1/overview).
+The `PESEL` library is available in the [Maven Central Repository](https://central.sonatype.com/artifact/io.github.viepovsky/pesel/2.0.2/overview).
 
 ### Gradle
 
 To use `PESEL` in a Gradle project, add the following line to your `build.gradle` file:
 
 ```java
-implementation 'io.github.viepovsky:pesel:2.0.1'
+implementation 'io.github.viepovsky:pesel:2.0.2'
 ```
 
 ### Maven
@@ -36,7 +36,7 @@ To use `PESEL` in a Maven project, add the following code to your `pom.xml` file
 <dependency>
     <groupId>io.github.viepovsky</groupId>
     <artifactId>pesel</artifactId>
-    <version>2.0.1</version>
+    <version>2.0.2</version>
 </dependency>
 ```
 
@@ -49,9 +49,9 @@ Once you have added the dependency, you can start using the `PESEL` library in y
 To validate a PESEL, you can use either the `Pesel` or `PeselValidator` class.
 
 ```java
-Pesel pesel = new Pesel("92082683499"); //may throw InvalidPeselException
+Pesel pesel = new Pesel("92082683499"); //if PESEL not valid it throws unchecked InvalidPeselException
 //or
-PeselValidator.assertIsValid("92082683499"); //may throw InvalidPeselException
+PeselValidator.assertIsValid("92082683499"); //if PESEL not valid it throws unchecked InvalidPeselException
 //or
 boolean isPeselValid = PeselValidator.isValid("92082683499"); //returns true or false
 ```
@@ -61,21 +61,21 @@ boolean isPeselValid = PeselValidator.isValid("92082683499"); //returns true or
 To decode a PESEL and retrieve information, use the `Pesel` class.
 
 ```java
-Pesel pesel = new Pesel("92082683499"); //may throw InvalidPeselException
+Pesel pesel = new Pesel("92082683499"); //if PESEL not valid it throws unchecked InvalidPeselException
 String gender = pesel.getGender(); // returns MALE or FEMALE
-LocalDate birthDate = pesel.getBirthDate();
+LocalDate birthDate = pesel.getBirthDate(); // returns date of birth as LocalDate object
 ```
 
 ### Retrieving PESEL digits
 
 To retrieve specific digits from a PESEL, use the `Pesel` class.
 
 ```java
-Pesel pesel = new Pesel("92082683499"); //may throw InvalidPeselException
-int birthDate = pesel.getBirthDateNumbers();
-int serial = pesel.getSerialNumbers();
-int gender = pesel.getGenderNumber();
-int control = pesel.getControlNumber();
+Pesel pesel = new Pesel("92082683499"); //if PESEL not valid it throws unchecked InvalidPeselException
+int birthDateDigits = pesel.getBirthDateDigits();
+int serialDigits = pesel.getSerialDigits();
+int genderDigit = pesel.getGenderDigit();
+int controlDigit = pesel.getControlDigit();
 ```
 
 ### Generating random PESEL
@@ -123,7 +123,7 @@ When using `Pesel` or PeselValidator to validate, they may throw an exception if
 The `InvalidPeselException` message includes information about the validation of the invalid PESEL, and is thrown when the PESEL:
 - has an invalid length (other than 11)
 - has invalid characters (characters other than digits)
-- has an invalid control number (e.g. is 5 but should be 7)
+- has an invalid control digit (e.g. is 5 but should be 7)
 - has an invalid birth date (e.g. the 32nd of any month)
 
 When using `PeselGeneratorParams`, if you pass an out-of-range date parameter, it will throw an `IllegalArgumentException`.

build.gradle

@@ -13,7 +13,7 @@ jacocoTestReport {
 }
 
 group 'io.github.viepovsky'
-version '2.0.1'
+version '2.0.2'
 
 repositories {
     mavenCentral()
@@ -39,7 +39,7 @@ publishing {
         mavenJava(MavenPublication) {
             groupId = 'io.github.viepovsky'
             artifactId = 'pesel'
-            version = "2.0.1"
+            version = "2.0.2"
             from components.java
 
             pom {

src/main/java/io/github/viepovsky/polishutils/pesel/InvalidPeselException.java

@@ -11,11 +11,12 @@
  * </ul>
  */
 public class InvalidPeselException extends RuntimeException {
+
     /**
      * Constructs a {@code InvalidPeselException} with the specified
      * detail message.
      *
-     * @param   message   the detail message.
+     * @param message the detail message.
      */
     InvalidPeselException(String message) {
         super(message);

src/main/java/io/github/viepovsky/polishutils/pesel/Pesel.java

@@ -8,7 +8,7 @@
  * A correct PESEL has 11 digits and contains information about the date of birth and gender.
  * It has the form of YYMMDDZZZXQ, where YYMMDD (digits 1-6) represents the date of birth, ZZZ (digits 7-9)
  * represents the unique serial number, and X (digit 10) determines the person's gender
- * (odd for males, even for females). The Q (digit 11) is a control sum number that verifies whether
+ * (odd for males, even for females). The Q (digit 11) is a control sum digit that verifies whether
  * a given PESEL is correct or not.
  * <p>
  * Upon construction, this class validates PESEL, it provides methods to decode and get gender and birthdate.
@@ -18,23 +18,25 @@
  * <blockquote><pre>
  *     Pesel pesel = new Pesel("92082683499");
  * </pre></blockquote>
- *     and then you can access the PESEL values:
+ * and then you can access the PESEL values:
  * <blockquote><pre>
  *     String gender = pesel.getGender();
  *     LocalDate birthDate = pesel.getBirthDate();
- *     int serialNumbers = pesel.getSerialNumbers();
+ *     int serialDigits = pesel.getSerialDigits();
  * </pre></blockquote>
  * Remember to catch exceptions upon construction. Passing a {@code null} argument to a constructor will
  * cause a {@link NullPointerException} to be thrown. Passing an invalid PESEL to a constructor will
- * cause an {@link InvalidPeselException} to be thrown.
+ * cause an unchecked {@link InvalidPeselException} to be thrown.
  *
  * @author Oskar Rajzner
  */
-public class Pesel extends PeselNumbers {
+public class Pesel extends PeselDigits {
+
     /**
      * The date of birth decoded from the given PESEL.
      */
     private final LocalDate birthDate;
+
     /**
      * The gender decoded from the given PESEL.
      */
@@ -52,18 +54,25 @@ public Pesel(String pesel) {
     }
 
     /**
-     * Private constructor of {@code Pesel} class. Creates a {@code PeselNumber} object,
-     * validates given PESEL, decodes and stores date of birth and gender.
+     * Private constructor of {@code Pesel} class.
+     * Validates given PESEL, decodes and stores date of birth, gender and sets PESEL digits.
      *
      * @param peselDecoder an instance of the {@code PeselDecoder} class
-     * @param pesel the PESEL number
+     * @param pesel        the PESEL number
      * @throws InvalidPeselException if the given PESEL is invalid
      */
     private Pesel(PeselDecoder peselDecoder, String pesel) {
-        super(pesel);
-        PeselValidator.assertIsValid(pesel);
+        super();
+
+        PeselValidator.assertIsPeselValid(pesel);
+
         this.birthDate = peselDecoder.decodeBirthDate(pesel);
         this.gender = peselDecoder.decodeGender(pesel);
+
+        setBirthDateDigits(pesel);
+        setSerialDigits(pesel);
+        setGenderDigit(pesel);
+        setControlDigit(pesel);
     }
 
     /**
@@ -74,6 +83,7 @@ private Pesel(PeselDecoder peselDecoder, String pesel) {
     public String getGender() {
         return String.valueOf(gender);
     }
+
     /**
      * Returns decoded date of birth of given PESEL number.
      *

src/main/java/io/github/viepovsky/polishutils/pesel/PeselDecoder.java

@@ -5,13 +5,15 @@
 /**
  * The {@code PeselDecoder} class decodes the date of birth and gender from PESEL
  * (Polish Personal Identification Number). This class is package-private
- * and is not intended for use outside of the org.viepovsky.pesel package.
+ * and is not intended for use outside the org.viepovsky.pesel package.
  *
  * @author Oskar Rajzner
  */
-class PeselDecoder {
+final class PeselDecoder {
+
     /**
      * Decodes the date of birth from given PESEL.
+     *
      * @param pesel the PESEL number
      * @return the date of birth as a LocalDate object
      */
@@ -46,6 +48,7 @@ LocalDate decodeBirthDate(String pesel) {
 
     /**
      * Decodes the gender from given PESEL.
+     *
      * @param pesel the PESEL number
      * @return the gender as a Pesel.Gender enum
      */

src/main/java/io/github/viepovsky/polishutils/pesel/PeselDigits.java

@@ -0,0 +1,116 @@
+package io.github.viepovsky.polishutils.pesel;
+
+/**
+ * The {@code PeselDigits} class holds the digits of a PESEL number as fields. Each field
+ * corresponds to a specific part of the PESEL (date of birth, serial number, gender, and
+ * control digit).
+ * <p>
+ * This class is package-private and is not intended for use outside the org.viepovsky.pesel package.
+ * <p>
+ *
+ * @author Oskar Rajzner
+ */
+abstract class PeselDigits {
+
+    /**
+     * Year, month, and day digits of the PESEL number in form of YYMMDD (digits 1-6).
+     */
+    private int birthDateDigits;
+
+    /**
+     * Unique serial digits of the PESEL in form of ZZZ (digits 7-9).
+     */
+    private int serialDigits;
+
+    /**
+     * Gender digit of the PESEL in form of X (digit 10).
+     */
+    private int genderDigit;
+
+    /**
+     * Control sum digit of the PESEL in form of Q (digit 11).
+     */
+    private int controlDigit;
+
+    /**
+     * Constructs a new {@code PeselDigits} object.
+     */
+    PeselDigits() {
+    }
+
+    /**
+     * Returns the year, month, and day digits of the PESEL number as an integer in the
+     * form of YYMMDD.
+     *
+     * @return an integer representing the year, month, and day digits of the PESEL number
+     */
+    public int getBirthDateDigits() {
+        return birthDateDigits;
+    }
+
+    /**
+     * Sets the year, month, and day digits of the PESEL number as an integer in the
+     * form of YYMMDD.
+     *
+     * @param pesel the PESEL number
+     */
+    void setBirthDateDigits(String pesel) {
+        birthDateDigits = Integer.parseInt(pesel.substring(0, 6));
+    }
+
+    /**
+     * Returns the unique serial digits of the PESEL as an integer in the form of ZZZ.
+     *
+     * @return an integer representing the unique serial digits of the PESEL
+     */
+    public int getSerialDigits() {
+        return serialDigits;
+    }
+
+    /**
+     * Sets the unique serial digits of the PESEL as an integer in the form of ZZZ.
+     *
+     * @param pesel the PESEL number
+     */
+    void setSerialDigits(String pesel) {
+        serialDigits = Integer.parseInt(pesel.substring(6, 9));
+    }
+
+    /**
+     * Returns the single digit representing the gender of the person associated with the
+     * PESEL as an integer.
+     *
+     * @return an integer representing the gender digit of the PESEL
+     */
+    public int getGenderDigit() {
+        return genderDigit;
+    }
+
+    /**
+     * Returns the single digit representing the gender of the person associated with the
+     * PESEL as an integer.
+     *
+     * @param pesel the PESEL number
+     */
+    void setGenderDigit(String pesel) {
+        genderDigit = Character.getNumericValue(pesel.charAt(9));
+    }
+
+    /**
+     * Returns the single digit representing the control sum of the PESEL as an integer.
+     *
+     * @return an integer representing the control sum of the PESEL
+     */
+    public int getControlDigit() {
+        return controlDigit;
+    }
+
+    /**
+     * Sets the single digit representing the control sum of the PESEL as an integer.
+     *
+     * @param pesel the PESEL number
+     */
+    void setControlDigit(String pesel) {
+        controlDigit = Character.getNumericValue(pesel.charAt(10));
+    }
+}

src/main/java/io/github/viepovsky/polishutils/pesel/PeselGenerator.java

@@ -38,22 +38,27 @@
  * @see PeselGeneratorParams
  */
 public class PeselGenerator {
+
     /**
      * Digits weights for calculating the control digit of the PESEL.
      */
     private static final int[] CONTROL_WEIGHTS = new int[]{1, 3, 7, 9, 1, 3, 7, 9, 1, 3};
+
     /**
      * A random number generator used for generating PESEL numbers.
      */
     private static final Random RANDOM = new Random();
+
     /**
      * The gender that will be included in the generated PESEL numbers.
      */
     private static PeselGeneratorParams.Gender gender;
+
     /**
      * The minimum date range from which a PESEL number will be generated.
      */
     private final LocalDate minDate;
+
     /**
      * The maximum date range to which a PESEL number will be generated.
      */
@@ -181,7 +186,6 @@ private static String getRandomSerialDigits() {
         return String.valueOf(RANDOM.nextInt(10)) + RANDOM.nextInt(10) + RANDOM.nextInt(10);
     }
 
-
     /**
      * Generates a random digit to represent the gender in the PESEL number. If a gender is specified,
      * the PESEL will be generated with that gender. If no gender is specified, the generated gender will be random.