From a836c15dd63d905408f18b0af65db5c30c4b9c69 Mon Sep 17 00:00:00 2001
From: Marc Wrobel <marc.wrobel@gmail.com>
Date: Thu, 21 Jul 2022 00:13:35 +0200
Subject: [PATCH] Add @LastVerification to document the last verification date
 of a list (#152)

---
 CHANGELOG.md                                  |  1 +
 .../fr/marcwrobel/jbanking/Agreement.java     | 29 ++++---------------
 .../fr/marcwrobel/jbanking/IsoCountry.java    | 10 +++----
 .../fr/marcwrobel/jbanking/IsoCurrency.java   |  9 +++---
 .../jbanking/internal/LastVerification.java   | 24 +++++++++++++++
 .../marcwrobel/jbanking/IsoCurrencyTest.java  |  5 +---
 6 files changed, 41 insertions(+), 37 deletions(-)
 create mode 100644 src/main/java/fr/marcwrobel/jbanking/internal/LastVerification.java

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 91844c3c..3e5b829c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,5 +34,6 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Enable experimental alerts for CodeQL (#145).
 - Set up Maven dependencies caching (#143).
 - Add a [`CODEOWNERS`](/CODEOWNERS) (#142).
+- Add `@LastVerification` to document the last verification date of a list (#152).
 
 ### Thanks
diff --git a/src/main/java/fr/marcwrobel/jbanking/Agreement.java b/src/main/java/fr/marcwrobel/jbanking/Agreement.java
index f25bc9ef..1fb577b5 100644
--- a/src/main/java/fr/marcwrobel/jbanking/Agreement.java
+++ b/src/main/java/fr/marcwrobel/jbanking/Agreement.java
@@ -3,6 +3,7 @@
 import static fr.marcwrobel.jbanking.IsoCountry.*;
 import static java.util.Collections.unmodifiableSet;
 
+import fr.marcwrobel.jbanking.internal.LastVerification;
 import java.util.Arrays;
 import java.util.EnumSet;
 import java.util.Set;
@@ -20,18 +21,13 @@ public enum Agreement {
    * agreement which enables the extension of the European Union's single market to member states of the European Free Trade
    * Association.
    *
-   * <p>
-   * This enum was last updated on 2022-07-20 based on information given on
-   * <a href=
-   * "https://ec.europa.eu/eurostat/statistics-explained/index.php/Glossary%3AEuropean_Economic_Area_%28EEA%29">europa.eu -
-   * European Economic Area (EEA)</a>.
-   *
    * @see <a href=
    *      "https://ec.europa.eu/eurostat/statistics-explained/index.php/Glossary%3AEuropean_Economic_Area_%28EEA%29">europa.eu -
    *      European Economic Area (EEA)</a>
    * @see <a href="https://wikipedia.org/wiki/European_Economic_Area">Wikipedia - European Economic Area</a>
    * @since 2.1.0
    */
+  @LastVerification("2022-07-20")
   EUROPEAN_ECONOMIC_AREA(AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IS, IE, IT, LV, LI, LT, LU, MT, NL, NO,
       PL, PT, RO, SK, SI, ES, SE, CH),
 
@@ -40,14 +36,11 @@ public enum Agreement {
    * in parallel with the European Union (EU), and all member states participate in the European Single Market and are part of
    * the Schengen Area. They are not, however, party to the European Union Customs Union.
    *
-   * <p>
-   * This enum was last updated on 2022-07-20 based on information given on
-   * <a href="https://www.efta.int/about-efta/the-efta-states">efta.int - The EFTA States</a>.
-   *
    * @see <a href="https://www.efta.int/about-efta/the-efta-states">efta.int - The EFTA States</a>
    * @see <a href="https://wikipedia.org/wiki/European_Free_Trade_Association">Wikipedia - European Free Trade Association</a>
    * @since 2.1.0
    */
+  @LastVerification("2022-07-20")
   EUROPEAN_FREE_TRADE_ASSOCIATION(IS, LI, NO, CH),
 
   /**
@@ -59,16 +52,13 @@ public enum Agreement {
    * <a href="https://wikipedia.org/wiki/Special_member_state_territories_and_the_European_Union">Special member state
    * territories</a> are not listed in this enum.
    *
-   * <p>
-   * This enum was last updated on 2022-07-20 based on information given on
-   * <a href="https://europa.eu/european-union/about-eu/countries_en">europa.eu - Countries</a>.
-   *
    * @see <a href="https://europa.eu/european-union/about-eu/countries_en">europa.eu - Countries</a>
    * @see <a href="https://wikipedia.org/wiki/European_Union">Wikipedia - European Union</a>
    * @see <a href="https://wikipedia.org/wiki/Special_member_state_territories_and_the_European_Union">Wikipedia - Special
    *      member state territories and the European Union</a>
    * @since 2.1.0
    */
+  @LastVerification("2022-07-20")
   EUROPEAN_UNION(AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI,
       ES, SE),
 
@@ -78,14 +68,11 @@ public enum Agreement {
    * outside the SEPA zone, namely French Polynesia, New Caledonia, Wallis and Futuna, the CFONB has defined a solution called
    * SEPA COM PACIFIQUE.
    *
-   * <p>
-   * This enum was last updated on 2022-07-20 based on information given in the CFONB article
-   * <a href="https://www.cfonb.org/sepa/leuro-et-les-territoires-du-pacifique">Le SEPA et les territoires du Pacifique</a>.
-   *
    * @see <a href="https://www.cfonb.org/sepa/leuro-et-les-territoires-du-pacifique">Le SEPA et les territoires du Pacifique</a>
    * @see <a href="https://wikipedia.org/wiki/Single_Euro_Payments_Area">Wikipedia</a>
    * @since 2.1.0
    */
+  @LastVerification("2022-07-20")
   SEPA_COM_PACIFIQUE(PF, NC, WF),
 
   /**
@@ -93,17 +80,13 @@ public enum Agreement {
    * transfers denominated in euro. The aim of SEPA is to improve the efficiency of cross-border payments and turn the
    * previously fragmented national markets for euro payments into a single domestic one.
    *
-   * <p>
-   * This enum was last updated on 2022-07-20 based on information given in
-   * <a href="https://www.europeanpaymentscouncil.eu/document-library/other/epc-list-sepa-scheme-countries">EPC409-09 - EPC List
-   * of SEPA Countries v2.6</a>.
-   *
    * @see <a href="https://www.europeanpaymentscouncil.eu/document-library/other/epc-list-sepa-scheme-countries">EPC409-09 EPC
    *      List of SEPA Countries v4.0 - February 2021</a>
    * @see <a href="https://www.iso13616.org/">IBAN registry</a>
    * @see <a href="https://wikipedia.org/wiki/Single_Euro_Payments_Area">Wikipedia</a>
    * @since 2.1.0
    */
+  @LastVerification("2022-07-20")
   SINGLE_EURO_PAYMENTS_AREA(
       // EU countries
       AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE,
diff --git a/src/main/java/fr/marcwrobel/jbanking/IsoCountry.java b/src/main/java/fr/marcwrobel/jbanking/IsoCountry.java
index 492ba9f9..cf6baf42 100644
--- a/src/main/java/fr/marcwrobel/jbanking/IsoCountry.java
+++ b/src/main/java/fr/marcwrobel/jbanking/IsoCountry.java
@@ -2,6 +2,7 @@
 
 import static java.util.Objects.requireNonNull;
 
+import fr.marcwrobel.jbanking.internal.LastVerification;
 import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.Map;
@@ -11,7 +12,8 @@
 /**
  * The countries, dependent territories, and special areas of geographical interest having an
  * <a href="https://wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements">Officially assigned</a> ISO 3166-1
- * code.
+ * code, <a href="https://www.iso.org/iso-3166-country-codes.html">as defined by International Organization for
+ * Standardization</a>.
  *
  * <p>
  * One exception has been made for Kosovo. Kosovo has a user-assigned code, XK, that is being used temporarily by the European
@@ -26,10 +28,7 @@
  * <li>make this enum easier to serialize (to JSON, in database...),
  * <li>prevent accidental duplicates.
  * </ul>
- *
- * <p>
- * This enum was last updated on 2022-07-20 based on information given in
- * <a href="https://www.iso.org/iso-3166-country-codes.html">International Organization for Standardization</a> website.
+ * .
  *
  * <p>
  * Usage:
@@ -46,6 +45,7 @@
  * @see <a href="https://www.iso.org/iso-3166-country-codes.html">ISO 3166 Country Codes</a>
  * @since 1.0
  */
+@LastVerification("2022-07-20")
 public enum IsoCountry {
   /**
    * Afghanistan (aka the Islamic Republic of Afghanistan).
diff --git a/src/main/java/fr/marcwrobel/jbanking/IsoCurrency.java b/src/main/java/fr/marcwrobel/jbanking/IsoCurrency.java
index cea7beee..b6cea00b 100644
--- a/src/main/java/fr/marcwrobel/jbanking/IsoCurrency.java
+++ b/src/main/java/fr/marcwrobel/jbanking/IsoCurrency.java
@@ -5,16 +5,13 @@
 import static java.util.Collections.unmodifiableSet;
 import static java.util.Objects.requireNonNull;
 
+import fr.marcwrobel.jbanking.internal.LastVerification;
 import java.util.*;
 
 /**
  * The currencies having an ISO 4217 code.
  *
  * <p>
- * Please be advised that this list is current as of 2013/05/26. Up-to-date list can be found for free on the
- * <a href="https://www.currency-iso.org/en/home/tables/table-a1.html"> currency-iso.org</a>.
- *
- * <p>
  * Note that enum entries are named after the ISO 4217 alphabetic code. This choice has been made in version 3.0.0 of jbanking
  * in order to :
  *
@@ -36,9 +33,11 @@
  * Assertion.assertTrue(currency.getCountries().contains(FR));
  * </pre>
  *
- * @see <a href="https://www.currency-iso.org/en/home/tables/table-a1.html">currency-iso.org</a>
+ * @see <a href="https://www.currency-iso.org/en/home/tables/table-a1.html">ISO 4217 - Currency Code Maintenance - Current
+ *      Currency &amp; Funds - List One</a>
  * @since 1.0
  */
+@LastVerification("2022-04-20")
 public enum IsoCurrency {
   /**
    * ADB (African Development Bank) Unit of Account.
diff --git a/src/main/java/fr/marcwrobel/jbanking/internal/LastVerification.java b/src/main/java/fr/marcwrobel/jbanking/internal/LastVerification.java
new file mode 100644
index 00000000..5f5e038b
--- /dev/null
+++ b/src/main/java/fr/marcwrobel/jbanking/internal/LastVerification.java
@@ -0,0 +1,24 @@
+package fr.marcwrobel.jbanking.internal;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.ElementType.TYPE;
+
+import java.lang.annotation.*;
+
+/**
+ * Document the last verification date of a list (of countries, of currencies...).
+ *
+ * <p>
+ * This enum is for jbanking internal use only : do not use it in your code !
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = { CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE })
+public @interface LastVerification {
+
+  /**
+   * Returns the last verification date of the annotated element.
+   * @return a non null date formatted as {@code yyyy-MM-dd} (e.g. 2022-07-20).
+   */
+  String value();
+}
diff --git a/src/test/java/fr/marcwrobel/jbanking/IsoCurrencyTest.java b/src/test/java/fr/marcwrobel/jbanking/IsoCurrencyTest.java
index 51a70b06..0aaab8dd 100644
--- a/src/test/java/fr/marcwrobel/jbanking/IsoCurrencyTest.java
+++ b/src/test/java/fr/marcwrobel/jbanking/IsoCurrencyTest.java
@@ -1,12 +1,9 @@
 package fr.marcwrobel.jbanking;
 
+import static fr.marcwrobel.jbanking.IsoCurrency.*;
 import static fr.marcwrobel.jbanking.IsoCurrency.Category.FUND;
 import static fr.marcwrobel.jbanking.IsoCurrency.Category.METAL;
 import static fr.marcwrobel.jbanking.IsoCurrency.Category.NATIONAL;
-import static fr.marcwrobel.jbanking.IsoCurrency.EUR;
-import static fr.marcwrobel.jbanking.IsoCurrency.USS;
-import static fr.marcwrobel.jbanking.IsoCurrency.XAU;
-import static fr.marcwrobel.jbanking.IsoCurrency.fromAlphabeticCode;
 import static java.util.Arrays.stream;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;