README.adoc 4.81 KB
Newer Older
Sascha Kohlmann's avatar
Sascha Kohlmann committed
1
2
= Krankenversichertennummer
:toc:
3

Sascha Kohlmann's avatar
Sascha Kohlmann committed
4
5
6
A Java implementation of the 10-digit invariant part of the German https://de.wikipedia.org/wiki/Krankenversichertennummer[Krankenversichertennummer] including validation against https://en.wikipedia.org/wiki/Luhn_algorithm[Luhn algorithm].
Also support for a https://en.wikipedia.org/wiki/General_Data_Protection_Regulation[GDPR] friendly quality assurance test Krankenversichertennummer is available.

Sascha Kohlmann's avatar
Sascha Kohlmann committed
7

Sascha Kohlmann's avatar
Sascha Kohlmann committed
8
9
10
11
12
13
14
15
16
17
18
== Usage

=== Dependendies

Resolve the dependency

==== Maven

[source,xml]
----
    <dependency>
Sascha Kohlmann's avatar
Sascha Kohlmann committed
19
        <groupId>tech.vbu.kvnr</groupId>
Sascha Kohlmann's avatar
Sascha Kohlmann committed
20
        <artifactId>vbu-krankenversichertennummer</artifactId>
Sascha Kohlmann's avatar
Sascha Kohlmann committed
21
        <version>1.0</version>
Sascha Kohlmann's avatar
Sascha Kohlmann committed
22
23
24
25
26
27
28
29
30
    </dependency>
----

==== Gradle

Groovy
[source,groovy]
----
    dependencies {
Sascha Kohlmann's avatar
Sascha Kohlmann committed
31
        implementation 'tech.vbu.kvnr:vbu-krankenversichertennummer:1.0'
Sascha Kohlmann's avatar
Sascha Kohlmann committed
32
33
34
35
36
37
38
    }
----

Kotlin
[source,kotlin]
----
    dependencies {
Sascha Kohlmann's avatar
Sascha Kohlmann committed
39
        implementation("tech.vbu.kvnr:vbu-krankenversichertennummer:1.0")
Sascha Kohlmann's avatar
Sascha Kohlmann committed
40
41
42
43
44
45
46
47
48
49
    }
----

=== Code

In your `module-info.java`:

[source,java]
----
    module your.modul.name {
Sascha Kohlmann's avatar
Sascha Kohlmann committed
50
        requires tech.vbu.krankenversichertennummer;
Sascha Kohlmann's avatar
Sascha Kohlmann committed
51
52
53
54
55
56
57
    }
----

In your code:

[source,java]
----
Sascha Kohlmann's avatar
Sascha Kohlmann committed
58
59
    final var insureeNumber = new Krankenversichertennummer("Q000000000");
    final var value = insureeNumber.value();
Sascha Kohlmann's avatar
Sascha Kohlmann committed
60

Sascha Kohlmann's avatar
Sascha Kohlmann committed
61
    System.out.format("Is test number: %b%n", insureeNumber.isTestNumber());
Sascha Kohlmann's avatar
Sascha Kohlmann committed
62
63
----

Sascha Kohlmann's avatar
Sascha Kohlmann committed
64
NOTE: the insuree number is an invalid test value for quality assurance environments.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
65
66
67
68
69
See <<quality_assurance,Quality assurance health insured numbers>> for more information.

The constructor throws two types of exceptions:

`NullPointerException`:: Thrown if and only if the given value of the constructor is a `null` reference.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
70
`KrankenversichertennummerException`:: Subtypes of `KrankenversichertennummerException` will be thrown if and only if the given value of the constructor is not a valid insuree number or not a defined quality assurance insuree number.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
71
This can be a `SyntaxException` if and only if the given value has a syntactical problem, like too short or if an actually numeric value is an alphabetic value.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
72
It is a `ChecksumException` if the Luhn checksum algorithm fails.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
73

Sascha Kohlmann's avatar
Sascha Kohlmann committed
74
75
See https://bkkvbu.gitlab.io/shared/vbu-krankenversichertennummer-jvm/apidocs/tech.vbu.krankenversichertennummer/module-summary.html[Javadoc] for more information.

Sascha Kohlmann's avatar
Sascha Kohlmann committed
76
[[quality_assurance]]
Sascha Kohlmann's avatar
Sascha Kohlmann committed
77
=== Quality assurance health insuree numbers
Sascha Kohlmann's avatar
Sascha Kohlmann committed
78

Sascha Kohlmann's avatar
Sascha Kohlmann committed
79
This implementation supports a list of _invalid_ quality assurance health insuree numbers.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
80
These numbers are from range `Q000000000` to `Q000000099`.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
81
The following list of numbers are excluded because such numbers are eventually valid insuree numbers which are in use:
Sascha Kohlmann's avatar
Sascha Kohlmann committed
82
83
84

- `Q000000005`, `Q000000018`, `Q000000020`, `Q000000032`, `Q000000044`, `Q000000057`, `Q000000069`, `Q000000071`, `Q000000083` and `Q000000095`

Sascha Kohlmann's avatar
Sascha Kohlmann committed
85
86
[[spi]]
==== Servie-provider interface
Sascha Kohlmann's avatar
Sascha Kohlmann committed
87

Sascha Kohlmann's avatar
Sascha Kohlmann committed
88
A service-provider interface is supported.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
89

Sascha Kohlmann's avatar
Sascha Kohlmann committed
90
91
See https://bkkvbu.gitlab.io/shared/vbu-krankenversichertennummer-jvm/apidocs/tech.vbu.krankenversichertennummer/tech/vbu/kvnr/spi/package-summary.html[Javadoc] for more information.

Sascha Kohlmann's avatar
Sascha Kohlmann committed
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
== Build

=== Java version

The supported minimum Java version is Java 11.

=== Build process

To build the project https://maven.apache.org/[Maven] 3.3.1 is required as a minimum Maven version.

To build and test the library, execute

[source,sh]
----
    mvn verify
----

in the base directory of the project.
This will create the main artifact and executes the <<spi,SPI>> test in the `spi-it` project.

== Naming & Versioning
Sascha Kohlmann's avatar
Sascha Kohlmann committed
113
114

In the context of German health insurances, the term _Krankenversichertennummer_ is a fixed term.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
115
For this reason, the term is not translated within this library e.g. in _HealthInsureeNumber_.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
116

Sascha Kohlmann's avatar
Sascha Kohlmann committed
117
118
119
120
121
The version is a simplified https://semver.org[semantic versioning].

- The _major_ number shows the release.
  This number will only change in case of incompatible changes.
  Such an incompatible change is also to increase the minimum JVM version with which the library is compatible.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
122
123
  An incompatible change will reset the _minor_ number to zero again.
- The _minor_ number will be increased with every compatible release.
Sascha Kohlmann's avatar
Sascha Kohlmann committed
124
125
  Fixed bugs also increase the minor version number.

Sascha Kohlmann's avatar
Sascha Kohlmann committed
126
127
There will be no _patch_ level version number.

Sascha Kohlmann's avatar
Sascha Kohlmann committed
128
129
130
131
132
133
134
135
136
137
138
139
140
141
== Copyright & License

Copyright 2021 https://www.meine-krankenkasse.de/[BKK VBU]

This copyrighted material is made available to anyone wishing to use, +
modify, copy, or redistribute it subject to the terms and conditions +
of the https://www.gnu.org/licenses/lgpl-3.0.en.html[GNU Lesser General Public License] version 3 or higher, as +
published by the https://www.fsf.org/[Free Software Foundation].

This library is distributed in the hope that it will be useful, +
but WITHOUT ANY WARRANTY; without even the implied warranty of +
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the https://www.gnu.org/licenses/lgpl-3.0.en.html[GNU Lesser General Public License] for more details.