diff --git a/docs/index.md b/docs/index.md index 9e5f425..8e3006a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,7 +7,15 @@ for other purposes, such as live input validation. The library is compatible for use in Android apps. It is in maintenance mode; I'll occasionally update it to the latest version of the IBAN registry, but I don't plan on developing any new features. -### Install +* [Installation](#Installation) +* [Usage Examples](#Use) +* [Version History](#Version-History) +* [Design Choices](#Design-Choices) +* [References](#References) +* [Alternatives](#Alternatives) +* [Copyright and License](#Copyright-and-License) + +### Installation Grab a package [from Github][download] or get it from Maven Central: @@ -17,7 +25,7 @@ Grab a package [from Github][download] or get it from Maven Central: nl.garvelink.oss iban - 1.6.0 + 1.6.1 ``` @@ -25,7 +33,7 @@ Grab a package [from Github][download] or get it from Maven Central: ```groovy dependencies { - compile 'nl.garvelink.oss:iban:1.6.0' + compile 'nl.garvelink.oss:iban:1.6.1' } ``` @@ -48,10 +56,10 @@ Obtain an `IBAN` instance using one of the static factory methods: `valueOf( )` iban = IBAN.valueOf( "BE68 5390 0754 7034" ); // The valueOf() method returns null if its argument is null. - iban.valueOf( null ); // null + IBAN.valueOf( null ); // null // The parse() method throws an exception if its argument is null. - iban.parse( null ); // IllegalArgumentException + IBAN.parse( null ); // IllegalArgumentException // IBAN does not implement Comparable, but a simple Comparator is provided. List ibans = getListOfIBANs(); @@ -66,10 +74,10 @@ Obtain an `IBAN` instance using one of the static factory methods: `valueOf( )` boolean valid = Modulo97.verifyCheckDigits( candidate ); // true // You can query whether an IBAN is of a SEPA-participating country - boolean isSepa = candidate.isSEPA(); // true + boolean isSepa = IBAN.parse(candidate).isSEPA(); // true // You can query whether an IBAN is in the SWIFT Registry - boolean isRegistered = candidate.isInSwiftRegistry(); // true + boolean isRegistered = IBAN.parse(candidate).isInSwiftRegistry(); // true // Modulo97 API methods take CharSequence, not just String. StringBuilder builder = new StringBuilder( "LU000019400644750000" ); @@ -87,33 +95,15 @@ Obtain an `IBAN` instance using one of the static factory methods: `valueOf( )` String branchId = IBANFieldsCompat.getBranchIdentifier( iban ); ``` -### Design Choices +[wjij]: http://blog.joda.org/2009/11/why-jsr-310-isn-joda-time_4941.html -I like the Joda-Time library and I try to follow the same design principles. I'm explicitly targetting Android, which -rules out some modern Java language constructs. I'm trying to keep the library as simple as I can. +### Version History -* The `IBAN` objects are immutable and the IBAN therein is non-empty and valid. There is no support for partial or - invalid IBANs. Note that "valid" isn't as strict as it could be: - * It checks that the length is correct (varies per country) and that the check digits are correct. - * The national format mask (such as `QA2!n4!a21!c`) is not enforced. This seems to me like more work than necessary. - The modulo-97 checksum catches most input errors anyway, and I don't want to force a memory-hungry regex check onto - Android users. Speaking of Android, this mask could be used for keyboard switching on an `IBANEditText`, but that's - for a different open-source project. - * Any national check digits are not enforced. Doing this right is more work than I want to put into this. I lack the - country-specific knowledge of all the gotchas and intricacies. If other countries' check digits are anything like - those in the Netherlands, they're going to differ by Bank Identifier. -* There is no way to configure extra restrictions such as "only SEPA countries" on the `IBAN.valueOf()` method. This, to - me, would look too much like Joda-Time's pluggable `Chronology` system, which leads to PoLS violations (background: [Why JSR-310 isn't Joda-Time][wjij]). -* There is no class to represent a partially entered IBAN or a potentially-invalid IBAN. I'm sure there are use cases - where you want to shift this sort of data around. As far as this library is concerned, if it's not an IBAN it's just a - string, and there already exist data types for dealing with those. -* Any feature that's not present in _all_ IBAN's is kept outside the `IBAN` class. Currently, that's the support for - extracting Bank and Branch identifiers, which lives in the `IBANFields` and `IBANFieldsCompat` classes. - -[wjij]: http://blog.joda.org/2009/11/why-jsr-310-isn-joda-time_4941.html +#### 1.6.1: 20 September 2019 +* "Bad input" exception messages no longer echo the input ([#14][i14]). +* No changes to IBAN formats -### Version history +[i14]:https://github.com/barend/java-iban/issues/14 #### 1.6.0: 23 August 2019 * Update to version 83 of the IBAN registry @@ -209,6 +199,30 @@ rules out some modern Java language constructs. I'm trying to keep the library a Montenegro, Netherlands, Norway, Poland, Portugal, Romania, San Marino, Serbia, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey, United Kingdom +### Design Choices + +I like the Joda-Time library and I try to follow the same design principles. I'm explicitly targetting Android, which +rules out some modern Java language constructs. I'm trying to keep the library as simple as I can. + +* The `IBAN` objects are immutable and the IBAN therein is non-empty and valid. There is no support for partial or + invalid IBANs. Note that "valid" isn't as strict as it could be: + * It checks that the length is correct (varies per country) and that the check digits are correct. + * The national format mask (such as `QA2!n4!a21!c`) is not enforced. This seems to me like more work than necessary. + The modulo-97 checksum catches most input errors anyway, and I don't want to force a memory-hungry regex check onto + Android users. Speaking of Android, this mask could be used for keyboard switching on an `IBANEditText`, but that's + for a different open-source project. + * Any national check digits are not enforced. Doing this right is more work than I want to put into this. I lack the + country-specific knowledge of all the gotchas and intricacies. If other countries' check digits are anything like + those in the Netherlands, they're going to differ by Bank Identifier. +* There is no way to configure extra restrictions such as "only SEPA countries" on the `IBAN.valueOf()` method. This, to + me, would look too much like Joda-Time's pluggable `Chronology` system, which leads to PoLS violations (background: [Why JSR-310 isn't Joda-Time][wjij]). +* There is no class to represent a partially entered IBAN or a potentially-invalid IBAN. I'm sure there are use cases + where you want to shift this sort of data around. As far as this library is concerned, if it's not an IBAN it's just a + string, and there already exist data types for dealing with those. +* Any feature that's not present in _all_ IBAN's is kept outside the `IBAN` class. Currently, that's the support for + extracting Bank and Branch identifiers, which lives in the `IBANFields` and `IBANFieldsCompat` classes. + ### References * **SWIFT IBAN Registry** diff --git a/src/main/java/nl/garvelink/iban/UnknownCountryCodeException.java b/src/main/java/nl/garvelink/iban/UnknownCountryCodeException.java index 8d51b5d..0cf5a30 100644 --- a/src/main/java/nl/garvelink/iban/UnknownCountryCodeException.java +++ b/src/main/java/nl/garvelink/iban/UnknownCountryCodeException.java @@ -22,7 +22,7 @@ public class UnknownCountryCodeException extends IllegalArgumentException { private final String failedInput; UnknownCountryCodeException(String failedInput) { - super("Unknown country code in " + failedInput); + super("Unknown country code in input"); this.failedInput = failedInput; } diff --git a/src/main/java/nl/garvelink/iban/WrongChecksumException.java b/src/main/java/nl/garvelink/iban/WrongChecksumException.java index 284bdcc..702372b 100644 --- a/src/main/java/nl/garvelink/iban/WrongChecksumException.java +++ b/src/main/java/nl/garvelink/iban/WrongChecksumException.java @@ -22,7 +22,7 @@ public class WrongChecksumException extends IllegalArgumentException { private final String failedInput; WrongChecksumException(String failedInput) { - super("Input \"" + failedInput + "\" failed checksum validation."); + super("Input failed checksum validation."); this.failedInput = failedInput; } diff --git a/src/main/java/nl/garvelink/iban/WrongLengthException.java b/src/main/java/nl/garvelink/iban/WrongLengthException.java index 76698b7..2bce008 100644 --- a/src/main/java/nl/garvelink/iban/WrongLengthException.java +++ b/src/main/java/nl/garvelink/iban/WrongLengthException.java @@ -24,7 +24,7 @@ public class WrongLengthException extends IllegalArgumentException { private final int expectedLength; WrongLengthException(String failedInput, int expectedLength) { - super("Input \"" + failedInput + "\" failed length validation: found " + failedInput.length() + ", but expect " + super("Input failed length validation: found " + failedInput.length() + ", but expect " + expectedLength + " for country code."); this.failedInput = failedInput; this.actualLength = failedInput.length();