Konzept Datum & Zeit

Die folgenden Begriffe sind zentral für den Baustein "Datum und Zeit" und werden hier definiert.

Die Bibliothek muss Datums- und Zeitwerte für die Anzeige auf grafischen Oberflächen in das in Deutschland gängige Format umwandeln können. Die Bibliothek muss mindestens die folgenden Darstellungen beherrschen (Bestandteile in Klammern sind optional):

Darüber hinaus muss die Bibliothek so flexibel sein, dass Abweichungen von den Standardformaten in den Anwendungen umgesetzt werden können.

Für die Verwendung an Schnittstellen muss die Bibliothek Datums- und Zeitwerte in eine ISO 8601-konforme Darstellung umwandeln können. Dazu muss standardmäßig folgendes Format benutzt werden:

Die Angabe der Zeitzone kann nur dann entfallen, wenn sie global festgelegt wurde oder aus dem Kontext heraus eindeutig hergeleitet werden kann.

Die Bibliothek muss Eingaben von Datums- und Zeitwerten über Schnittstellen aus einer ISO 8601-konformen Darstellung einlesen können.

Eingaben über grafische Oberflächen muss die Bibliothek aus den in Deutschland gängigen Formaten in einen entsprechenden Datums- oder Zeitwert umwandeln können. Die unterstützten Formate werden in den folgenden Abschnitten definiert.

Die Bibliothek muss bestimmte Berechnungen auf Datumswerten, Zeitwerten und Zeiträumen bereitstellen.

Die Bibliothek muss sogenannte ungewisse Datumswerte verarbeiten können. Dabei sind Teile eines Datumswerts zunächst ungewiss. Die Bibliothek muss die Möglichkeit vorsehen, solche ungewissen Angaben später zu konkretisieren.

Konkretisierung eines ungewissen Datums zeigt einen beispielhaften Verlauf einer Konkretisierung eines Datumswerts: Das Datum ist zunächst ungewiss, wird durch spätere Erkenntnisse aber schlussendlich zu einem Datum ohne Ungewissheit konkretisiert. Es gibt eine Einschränkung bei der Konkretisierung ungewisser Datumswerte. Da die Ungewissheit durch Zeiträume abgebildet wird, müssen ungewisse Datumswerte immer einen in sich abgeschlossenen Zeitraum bilden. Nicht abbildbar ist z.B. "Geburtsdatum: der 24. eines beliebigen Monats des Jahres 1976", da dies nicht als Zeitraum darstellbar ist.

Zur Unterstützung des Tests muss die Bibliothek es erlauben, die aktuelle Systemzeit mit eigenen Werten zu überschreiben, um Abläufe in der Vergangenheit oder Zukunft darstellen zu können.

Die Bibliothek besitzt die folgenden Maven-Koordinaten:

Das Stammpackage für alle Klassen der Umsetzung setzt sich aus Group-ID und Artifact-ID zusammen und lautet: de.bund.bva.isyfact.datetime.

Die Bibliothek muss zur Umsetzung der Anforderungen so stark wie möglich auf die im JSR 310 beschriebene API setzen. Falls einige der Anforderungen aus dem Kapitel Anforderungen komplett durch die Funktionalität dieser API abgedeckt sind, wird in den Nutzungsvorgaben die entsprechende Verwendung der API mit Verweis auf die Standarddokumentation knapp erläutert. Abweichungen von der API oder eigene Implementierungen bereits vorhandener Funktionalität müssen in den Nutzungsvorgaben begründet und beschrieben werden.

Innerhalb von Anwendungen können alle Typen des "JSR 310: Date and Time API" verwendet werden, insofern dieses Konzept an anderer Stelle die Nutzung nicht weiter einschränkt.

Die Bibliothek muss sicherstellen, dass die gesamte Funktionalität für alle geeigneten Typen angeboten wird und an geeigneten Stellen sinnvolle Umwandlungen (d.h. ohne Verlust von Daten oder Genauigkeit) möglich sind.

Die Bibliothek wird zur Umsetzung der Darstellung sowie Eingabe keine konkrete Technologie zur Erstellung grafischer Oberflächen unterstützen. Stattdessen muss sie die Funktionalität auf Basis der Standardbibliothek bereitstellen, damit sie leicht von GUI-Technologien verwendet werden kann. Zum Ausgeben von Werten und Einlesen von Eingaben muss die Bibliothek die Klasse java.time.format.DateTimeFormatter verwenden und, falls nötig, auf die in Deutschland gängigen Formate hin konfigurieren oder Funktionen anbieten, um gängige Formate leicht ausgeben und einlesen zu können. Eine Reihe von Standardformaten, welche die Bibliothek unterstützen muss, sind im Kapitel Darstellung beschrieben.

Die Bibliothek muss zur Behandlung ungewisser Datumswerte die folgende Funktionalität bereitstellen:

Bisherige Implementierungen ungewisser Datumswerte setzen immer den Sonderfall um, bei dem entweder der Tag, Tag und Monat oder alle Teile eines Datumswerts unbekannt sind. Die Anzeige und Eingabe dieser unbekannten Werte erfolgt hierbei über Nullen, wie die Bisherige Umsetzung ungewisser Datumswerte zeigt.

Der Hauptnachteil dieser Umsetzung besteht darin, dass die Datumswerte durch ihre interne Darstellung als Zeichenkette nur mit großem Aufwand mit anderen Datumswerten verglichen bzw. in Berechnungen verwendet werden können. Trotzdem muss die Bibliothek ungewisse Datumswerte dieser Art einlesen und ausgeben können. Die Werte werden beim Einlesen intern in entsprechende Zeiträume umgewandelt und bei der Darstellung wieder in die ursprüngliche Form überführt. Eine Übersicht dieses Vorgangs zeigt die Umsetzung der Sonderfälle (mit Nullen).

Des Weiteren muss die Bibliothek die Eingabe unbekannter Datumsbestandteile mittels "x" unterstützen. Diese Möglichkeit wird die Eingabe unbekannter Datumsbestandteile mittels Nullen mittelfristig ablösen und unterstützt Eingaben im ISO-8601 Datumsformat. Eine Übersicht der so umgesetzten Spezialfälle zeigt die Umsetzung der Sonderfälle (mit "x").

Die Umsetzung der Testunterstützung geschieht über das Mocken der Klasse java.time.Clock. Dazu muss die Bibliothek bei der Erzeugung von Datums- und Zeitangaben die Varianten mit einer Clock als Parameter benutzen und in der Konfiguration eine Clock als Abhängigkeit definieren. Des Weiteren müssen sich auch Anwendungen an diese Vorgabe halten, um die Testunterstützung nutzen zu können. Insbesondere sind Aufrufe von System.currentTimeMillis() sowie der Varianten von now() auf Typen der Datums- und Zeittypen ohne Verwendung einer Clock bei Nutzung dieses Bausteins verboten!