From 005115c14b936a1c2c16ccd0ce3273e416d4d1db Mon Sep 17 00:00:00 2001 From: Marc Wrobel Date: Sat, 15 Oct 2022 10:29:21 +0200 Subject: [PATCH] Fix Bic, CreditorIdentifier and Iban documentation (closes #209) It was not explicit that lowercase characters were accepted. --- CHANGELOG.md | 2 + .../java/fr/marcwrobel/jbanking/bic/Bic.java | 21 ++++++----- .../jbanking/creditor/CreditorIdentifier.java | 37 +++++++++++-------- .../fr/marcwrobel/jbanking/iban/Iban.java | 9 +++++ .../jbanking/internal/AsciiCharacters.java | 4 +- .../jbanking/swift/SwiftPattern.java | 4 +- 6 files changed, 49 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32dc682..e284b54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - (**breaking change**) `Iban.isValid(String)` or `IbanCheckDigit.validate(String)` return `false` instead of raising an `IllegalArgumentException` with invalid IBAN check digit (e.g. `00`, `01`, or `99`). +- Fix `Bic`, `CreditorIdentifier` and `Iban` documentation (#209). It was not explicit that lowercase characters were + accepted. ### Deprecated diff --git a/src/main/java/fr/marcwrobel/jbanking/bic/Bic.java b/src/main/java/fr/marcwrobel/jbanking/bic/Bic.java index 29c99a6..eaad3c5 100644 --- a/src/main/java/fr/marcwrobel/jbanking/bic/Bic.java +++ b/src/main/java/fr/marcwrobel/jbanking/bic/Bic.java @@ -6,8 +6,8 @@ import java.util.Optional; /** - * A Business Identifier Code (also known as BIC, SWIFT-BIC, BIC code, SWIFT ID or SWIFT code, Business Entity Identifier or - * BEI) as specified by ISO 9362:2009. + * A Business Identifier Code (also known as BIC, SWIFT-BIC, BIC code, SWIFT ID or SWIFT code, Business Entity + * Identifier or BEI) as specified by ISO 9362:2009. * *

* A BIC is either eight (BIC8) or eleven (BIC11) characters made up of : @@ -20,8 +20,8 @@ * * *

- * Where an 8-digit code is given, it is assumed that it refers to the primary office. The primary office is always designated - * by the branch code {@value #PRIMARY_OFFICE_BRANCH_CODE}). + * Where an 8-digit code is given, it is assumed that it refers to the primary office. The primary office is always + * designated by the branch code {@value #PRIMARY_OFFICE_BRANCH_CODE}). * *

* Instances of this class are immutable and thread-safe. @@ -86,10 +86,10 @@ public final class Bic implements Serializable { private final String normalizedBic; /** - * Create a new bic from the given string. + * Create a new BIC from the given string. * *

- * The given string may be a BIC8 or a BIC11. + * The given string may be a BIC8 or a BIC11. Uppercase and lowercase characters are accepted. * * @param bic8Or11 A non-null String. * @throws IllegalArgumentException if the given string is {@code null} @@ -118,7 +118,10 @@ public Bic(final String bic8Or11) { } /** - * Check whether the given string is valid BIC. + * Check whether the given string is a valid BIC. + * + *

+ * The given string may be a BIC8 or a BIC11. Uppercase and lowercase characters are considered valid. * * @param bic A String. * @return {@code true} if the given string is valid BIC, otherwise {@code false}. @@ -242,8 +245,8 @@ public Bic asTestBic() { * Indicates whether some other object is “equal to” this one. * *

- * To be equals to this one the other object must be a {@link Bic} and the BICs normalized form (see {@link #toString()}) must - * be equal. + * To be equals to this one the other object must be a {@link Bic} and the BICs normalized form (see + * {@link #toString()}) must be equal. * * @param o the object with which to compare. * @return {@code true} if this object is the same as the obj argument or {@code false} otherwise. diff --git a/src/main/java/fr/marcwrobel/jbanking/creditor/CreditorIdentifier.java b/src/main/java/fr/marcwrobel/jbanking/creditor/CreditorIdentifier.java index 28ab320..ea8b5a3 100644 --- a/src/main/java/fr/marcwrobel/jbanking/creditor/CreditorIdentifier.java +++ b/src/main/java/fr/marcwrobel/jbanking/creditor/CreditorIdentifier.java @@ -8,22 +8,23 @@ /** * A Creditor Identifier (CI) code as specified by the - * EPC. + * + * EPC. * *

- * CI structure: + * The CI structure is: * *

* *

- * This class handles validation of the check digit and validation of the Creditor Identifier Structure described above without - * going into the validation of the national identifier. + * This class handles validation of the check digit and validation of the Creditor Identifier Structure described above + * without going into the validation of the national identifier. * *

* Instances of this class are immutable and thread-safe. @@ -44,8 +45,8 @@ * Assertions.assertEquals("123456", ci.getNationalIdentifier()); * * - * @see EPC - * Creditor Identifier Overview + * @see + * EPC Creditor Identifier Overview */ public final class CreditorIdentifier implements Serializable { @@ -77,10 +78,13 @@ public final class CreditorIdentifier implements Serializable { /** * Create a new Creditor Identifier from the given string. * + *

+ * Uppercase and lowercase characters are accepted. + * * @param creditorId A non-null String. * @throws IllegalArgumentException if the given string is {@code null} - * @throws CreditorIdentifierFormatException if the given string does not match {@value #REGEX} or if its country code is not - * known in {@link fr.marcwrobel.jbanking.IsoCountry} or if its check digit is wrong + * @throws CreditorIdentifierFormatException if the given string does not match {@value #REGEX} or if its country code + * is not known in {@link fr.marcwrobel.jbanking.IsoCountry} or if its check digit is wrong */ public CreditorIdentifier(String creditorId) { if (creditorId == null) { @@ -107,10 +111,11 @@ public CreditorIdentifier(String creditorId) { } /** - * Create a new Creditor Identifier from the given country code, the creditor business code and the creditor national id. + * Create a new Creditor Identifier from the given country code, the creditor business code and the creditor national + * identifier. * *

- * The check digit is automatically calculated. + * The check digit is automatically calculated. Uppercase and lowercase characters are accepted. * * @param country A non-null IsoCountry. * @param businessCode A non-null String. @@ -185,9 +190,12 @@ private static String removeBusinessCode(String creditorIdentifier) { } /** - * Validates the given Creditor Identifier String. + * Check whether the given string is a valid creditor identifier. * - * @param creditorIdentifier A String. + *

+ * Uppercase and lowercase characters are considered valid. + * + * @param creditorIdentifier a String. * @return {@code true} if the given String is a valid Creditor Identifier, {@code false} otherwise. */ public static boolean isValid(String creditorIdentifier) { @@ -196,7 +204,6 @@ public static boolean isValid(String creditorIdentifier) { } String normalizedCreditorId = normalize(creditorIdentifier); - if (!isWellFormatted(normalizedCreditorId)) { return false; } diff --git a/src/main/java/fr/marcwrobel/jbanking/iban/Iban.java b/src/main/java/fr/marcwrobel/jbanking/iban/Iban.java index 477688b..3461f89 100644 --- a/src/main/java/fr/marcwrobel/jbanking/iban/Iban.java +++ b/src/main/java/fr/marcwrobel/jbanking/iban/Iban.java @@ -71,6 +71,9 @@ public final class Iban implements Serializable { /** * Create a new IBAN from the given country code and BBAN. * + *

+ * Uppercase and lowercase characters are accepted. + * * @param country A non-null IsoCountry. * @param bban A non-null String. * @throws IllegalArgumentException if either the IsoCountry or BBAN is {@code null} @@ -106,6 +109,9 @@ public Iban(IsoCountry country, String bban) { /** * Create a new IBAN from the given string. * + *

+ * Uppercase and lowercase characters are accepted. + * * @param iban A non-null String. * @throws IllegalArgumentException if the given string is {@code null} * @throws IbanFormatException if the given string is not a valid IBAN. @@ -141,6 +147,9 @@ public Iban(String iban) { /** * Validates the given IBAN String. * + *

+ * Uppercase and lowercase characters are considered valid. + * * @param iban A String. * @return {@code true} if the given String is a valid IBAN, {@code false} otherwise. */ diff --git a/src/main/java/fr/marcwrobel/jbanking/internal/AsciiCharacters.java b/src/main/java/fr/marcwrobel/jbanking/internal/AsciiCharacters.java index ff6ee61..6d0f788 100644 --- a/src/main/java/fr/marcwrobel/jbanking/internal/AsciiCharacters.java +++ b/src/main/java/fr/marcwrobel/jbanking/internal/AsciiCharacters.java @@ -33,7 +33,7 @@ public static boolean isAlphabetic(final char c) { /** *

- * Checks whether the character is ASCII 7 bit alphabetic upper case. + * Checks whether the character is ASCII 7 bit alphabetic uppercase. *

* * 
@@ -54,7 +54,7 @@ public static boolean isUpperAlphabetic(final char c) {
 
   /**
    * 

-   * Checks whether the character is ASCII 7 bit alphabetic lower case.
+   * Checks whether the character is ASCII 7 bit alphabetic lowercase.
    * 

    *
    * 
diff --git a/src/main/java/fr/marcwrobel/jbanking/swift/SwiftPattern.java b/src/main/java/fr/marcwrobel/jbanking/swift/SwiftPattern.java
index 58da9bd..b54cf38 100644
--- a/src/main/java/fr/marcwrobel/jbanking/swift/SwiftPattern.java
+++ b/src/main/java/fr/marcwrobel/jbanking/swift/SwiftPattern.java
@@ -37,7 +37,7 @@
  * 
  * 
  * c
- * upper and lower case alphanumeric characters (A-Z, a-z and 0-9)
+ * uppercase and lowercase alphanumeric characters (A-Z, a-z and 0-9)
  * 
  * 
  * e
@@ -58,7 +58,7 @@
  *
  * 
    
  * 
  • {@code 4!n} : four digits
- * 
  • {@code 4!c3!a} : four upper or lower case alphanumeric characters followed by three upper case
+ * 
  • {@code 4!c3!a} : four uppercase or lowercase alphanumeric characters followed by three upper case
  * letters
  * 
  • {@code 2!e4!a} : two spaces followed by four upper case letters
  *