Konzept Datum & Zeit

Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Java Bibliothek / IT-System

Name	Art	Version
isy-datetime	Bibliothek	3.2.x

Name

Art

Version

isy-datetime

Bibliothek

3.2.x

1. Einleitung

Dieses Dokument beschreibt die konzeptionellen Grundlagen der Verarbeitung von Datums- und Zeitwerten in der IsyFact. Es definiert Vorgaben für die einheitliche Verwendung von Datums- und Zeitfunktionen sowie die Behandlung von Datums- und Zeitwerten in Anwendungen und bildet so die Grundlage einer technisch und fachlich einheitlichen Umsetzung.

Die aus diesem Dokument abgeleitete Umsetzung der Verarbeitung von Datums- und Zeitwerten im Rahmen der Anwendungsentwicklung ist in den Nutzungsvorgaben beschrieben.

Sowohl dieses Dokument als auch das Umsetzungsdokument bedienen sich Projekterfahrungen sowie Best Practices und setzen auf die Datums- und Zeitfunktionen des JSR 310 („Date and Time API“), die mit Java 8 eingeführt wurden.

JSR 310: Date and Time API

2. Aufbau und Zweck des Dokuments

Ziel des Dokuments ist die Definition einheitlicher Vorgaben für die Verarbeitung von Datums- und Zeitwerten unter Berücksichtigung fachlicher und technischer Anforderungen.

Das Dokument ist entsprechend dieser Zielsetzungen folgendermaßen aufgebaut:

Zunächst werden die Anforderungen an die Verarbeitung von Datums- und Zeitwerten definiert, welche die Grundlage für das nachfolgende Kapitel bilden.

Anschließend werden die Vorgaben zur Verwendung von Datums- und Zeitwerten innerhalb der Anwendungen sowie zur Umsetzung in der zu diesem Baustein gehörenden Bibliothek definiert.

3. Anforderungen

Im Folgenden werden die Anforderungen an die Verarbeitung von Datums- und Zeitwerten definiert. Diese bilden die Grundlage für die Vorgaben im darauffolgenden Kapitel.

3.1. Definitionen

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

3.1.1. Datumswert

Datumswerte sind Daten, in denen Angaben zu einem kalendarischen Datum enthalten sind. Typische Bestandteile eines kalendarischen Datums sind Angaben zu Jahr, Monat und Tag. Datumswerte können Zeitwerte enthalten, müssen aber nicht.

Beispiele:

17. Juli 2017 (reiner Datumswert)
9. Juli 2017 14:50 MESZ (Datumswert mit Zeitwert)

3.1.2. Zeitwert

Zeitwerte sind Daten, in denen Angaben zu einem Zeitpunkt enthalten sind. Typische Bestandteile eines Zeitpunkts sind Angaben zu Stunde, Minute, Sekunden und Zeitzone. Zeitwerte können Teil von Datumswerten sein, aber selbst keine Datumswerte enthalten.

Beispiele:

05:04:23.233 GMT (Zeitwert mit Zeitzone)
14:50 (Zeitwert, bestehend nur aus Stunde und Minute)

3.1.3. Dauer

Eine Dauer ist eine quantifizierte Menge einer Zeiteinheit (z.B. 37 Sekunden, 14 Tage, 3 Jahre). Sie beschreibt eine zeitliche Länge unabhängig konkreter zeitlicher Angaben (z.B. Länge eines Spielfilms). In Verbindung mit einer Datums- oder Zeitangabe wird sie genutzt, um einen Zeitraum zu definieren (z.B. die Ausstrahlung des Spielfilms startet um 20:15 Uhr und endet um 21:50 Uhr).

Für die Zeiteinheiten gelten folgende Abkürzungen, welche für Ein- und Ausgabe benutzt werden können:

Tabelle 1. Abkürzungen für Zeiteinheiten
Abkürzung	Zeiteinheit
ms	Millisekunde
s	Sekunde
min	Minute
h	Stunde
d	Tag
a	Jahr

3.1.4. Zeitraum

Zeiträume bestehen aus zwei Datums- oder Zeitangaben, die den Start und das Ende eines Zeitraums markieren. Die Dauer des Zeitraums ist die Differenz aus Ende und Start.

3.2. Darstellung

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):

(Montag,) 17. Juli 2017 14:35:19 (MESZ)
17.07.2017 14:35:19 (+02:00)
17.07.2017
14:35:19

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:

yyyy-MM-dd’T’HH:mm:ssZ

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

3.3. Eingabe

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.

3.3.1. Datumswert

Eingaben von Datumswerten müssen Zeichenketten in folgendem Format sein:

<Tag>.<Monat>.<Jahr> <Zeitwert>

Tabelle 2. Eingabeformate der Felder von Datumswerten
Feld	Format	Beispiel	Pflichtfeld
Tag	Ganzzahl (1-31)	3, 03, 14	Ja
Monat	Ganzzahl (1-12)	5, 07, 11	Ja
Jahr	Ganzzahl (1-9999)	9, 476, 2013	Ja
Zeitwert	s. Kapitel Zeitwert		Nein

Tabelle 2 zeigt die möglichen Formate der einzelnen Felder. Anders als in der Anzeige sind keine textuellen Formate für z.B. Wochentage („Montag“) oder Monate („Dezember“) erlaubt. Das Jahr wird immer vollständig interpretiert und darf nicht verkürzt eingegeben werden (z.B. „69“ für „1969“). Anwendungen können eine solche Logik vorsehen, müssen die Jahreszahlen allerdings immer vollständig an den Baustein übergeben.

3.3.2. Zeitwert

Eingaben von Zeitwerten müssen Zeichenketten in folgendem Format sein:

<Stunde>:<Minute>:<Sekunde>.<Sekundenbruchteile> <Zeitzone>

Tabelle 3. Eingabeformate der Felder von Zeitwerten
Feld	Format	Beispiel	Pflichtfeld
Stunde	Ganzzahl (0-23)	0, 5, 08, 23	Ja
Minute	Ganzzahl (00-59)	00, 04, 23, 59	Ja
Sekunde	Ganzzahl (00-59)	00, 08, 44, 59	Nein
Sekunden-bruchteile	max. neunstellige Ganzzahl (1-999999999)	127 (ms), 235674 (µs), 349672834 (ns)	Nein
Zeitzone	Abweichung von UTC oder Name der Zeitzone	+02:30, -05:00 oder CET, Europe/Berlin	Nein

Tabelle 3 zeigt die möglichen Formate der einzelnen Felder. Alle Angaben außer Stunden müssen vollständig sein und bei Bedarf mit einer vorangestellten Null versehen werden. Bei Sekundenbruchteilen reichen üblicherweise drei Nachkommastellen, was einer Genauigkeit im Millisekundenbereich entspricht.

3.3.3. Dauer

Eingaben einer Dauer müssen Zeichenketten in folgendem Format sein:

<Anzahl><Zeiteinheit> (<Anzahl><Zeiteinheit> …)

Tabelle 4. Eingabeformate der Felder von Zeitwerten
Feld	Format
Anzahl	Ganzzahl
Zeiteinheit	Abkürzung der Zeiteinheit (s. Tabelle Tabelle 1)

Eine Dauer muss mindestens eine Zeiteinheit beinhalten („37s“), kann aber auch aus mehreren bestehen („1h 28min“). Die Zeiteinheiten müssen von der gröbsten (Jahr) zur feinsten (Millisekunde) hin sortiert sein.

3.3.4. Zeitraum

Zeiträume sind kein eigener Datentyp, sondern werden durch zwei Werte beschrieben. So gibt es zwei Möglichkeiten, einen Zeitraum darzustellen. Entweder

Ein Anfang und ein Ende beschrieben durch zwei Datums- oder Zeitwerte oder
Ein Anfang beschrieben durch einen Datums- oder Zeitwert sowie eine Dauer.

Die Bibliothek muss zur Eingabe eines Zeitraums diese Kombinationen von Werten unterstützen, deren Format gemäß der Anforderungen der Kapitel Datumswert bis Dauer beschaffen sein muss. Tabelle 5 zeigt Beispiele für die Eingabewerte von Zeiträumen.

Tabelle 5. Eingabewerte für Zeiträume
1. Wert	2. Wert	Beispiel
Datumswert	Datumswert	12.7.2017 14:00, 13.09.2018 19:00
Datumswert	Dauer	12.8.2013, 14 d
Zeitwert	Zeitwert	13:40:00, 15:45:12
Zeitwert	Dauer	12:00, 90min 15s

3.4. Persistierung

Die Persistierung von Angaben zu Datum, Zeit, Dauer, Zeiträumen und ungewissen Datums- und Zeitangaben wird durch den Baustein JPA/Hibernate behandelt.

3.5. Berechnungen

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

3.5.1. Datums- & Zeitwert

Die Bibliothek muss die folgenden Berechnungen auf Datums- & Zeitwerten ermöglichen:

Chronologische Sortierung einer Menge von Datums- und Zeitwerten
Chronologische Vergleiche zwischen Datums- und Zeitwerten
(„früher als“, „später als“, „gleichzeitig“)
Ermittlung des „Tagesdatums“ (der zeitliche Anteil eines Datumswerts wird auf 0, d.h. auf Mitternacht, gestellt)
Berechnung des Abstands („Dauer“) zwischen zwei Datums- oder Zeitwerten
Addition und Subtraktion von Datums- und Zeitwerten mit einer Dauer
Prüfung, ob zwei Datumswerte für zwei direkt aufeinanderfolgende Tage stehen ("Liegt der 28.2.2016 direkt vor dem 1.3.2016?“)
Berechnung des nächsten Werktags nach einem übergebenen Datumswert

3.5.2. Zeitraum

Die Bibliothek muss die folgenden Berechnungen auf Zeiträumen ermöglichen:

Prüfung, ob ein Datumswert in einem Zeitraum liegt
- Liegt der 18. Juli 2017 zwischen dem 4. Juli 2016 und dem 6. Dezember 2017?
Prüfung, ob sich zwei Zeiträume überlappen

3.6. Ungewisse Datums- und Zeitwerte

Die Bibliothek muss sogenannte ungewisse Datums- und Zeitwerte verarbeiten können. Dabei sind Teile eines Datums- oder Zeitwerts zunächst ungewiss. Die Bibliothek muss die Möglichkeit vorsehen, solche ungewissen Angaben später zu konkretisieren.

Tabelle 6. Konkretisierung eines ungewissen Datums
Erkenntnisse	Wert
Initiale Erkenntnis: Vom Geburtsdatum einer Person ist nur das Jahr bekannt	Geburtsdatum: 1.1.1976 – 31.12.1976
Zusätzliche Erkenntnis: Die Person ist im Juni des Jahres geboren. Der Tag ist zweistellig.	Geburtsdatum: 10.6.1976 – 30.6.1976
Zusätzliche Erkenntnis: Die Person ist am 24. geboren.	Geburtsdatum: 24.6.1976 – 24.6.1976

Tabelle 6 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 Datums- und Zeitwerte. Da die Ungewissheit durch Zeiträume abgebildet wird, müssen ungewisse Datums- und Zeitwerte 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.

Die Anforderungen zur Konkretisierung gelten ebenso für Zeitangaben. Tabelle 7 verdeutlicht dies in einem beispielhaften Verlauf.

Tabelle 7. Konkretisierung einer ungewissen Zeit
Erkenntnisse	Wert
Initiale Erkenntnis: Das Ereignis fand nach Mittag statt.	Start des Ereignisses: 12:01 – 23:59
Zusätzliche Erkenntnis: Das Ereignis fand vor 18 Uhr statt.	Start des Ereignisses: 12:01 – 17:59
Zusätzliche Erkenntnis: Das Ereignis fand um Viertel nach Drei statt.	Start des Ereignisses: 15:15 – 15:15

3.7. Testunterstützung

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.

4. Vorgaben

Die folgenden architektonischen und technischen Vorgaben beziehen sich auf die Umsetzung der in Kapitel Anforderungen genannten Anforderungen in der zu diesem Baustein gehörenden Bibliothek.

4.1. Namenskonventionen

Die Bibliothek besitzt die folgenden Maven-Koordinaten:

Group-ID: de.bund.bva.isyfact
Artifact-ID: isy-datetime

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

4.2. Bedeutung der Standardbibliothek

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.

4.3. Verwendung der Standardbibliothek

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.

4.4. Darstellung & Eingabe

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.

4.5. Ungewisse Datums- und Zeitwerte

Die Bibliothek muss zur Behandlung ungewisser Datums- und Zeitwerte die folgende Funktionalität bereitstellen:

Definition der Datenobjekte zur Verwendung ungewisser Datums- und Zeitwerte im Anwendungskern
Definition der Transportobjekte zur Übermittlung ungewisser Datums- und Zeitwerte über Schnittstellen
Formatierung ungewisser Daten zur Anzeige
Einlesen ungewisser Daten nach Eingabe durch Anwender

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 Tabelle 8 zeigt.

Tabelle 8. Bisherige Umsetzung ungewisser Datumswerte
Sonderfall	Eingabe / Darstellung	Intern
Tag unbekannt	00.05.1966	Zeichenkette: „00.05.1966“
Tag und Monat unbekannt	00.00.1966	Zeichenkette: „00.00.1966“
Datum komplett unbekannt	00.00.0000	Zeichenkette: „00.00.0000“

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 Tabelle 9.

Tabelle 9. Umsetzung der Sonderfälle (mit Nullen)
Sonderfall	Eingabe / Darstellung	Intern
Tag unbekannt	00.05.1966	Zeitraum: 1.5.1966 – 31.5.1966
Tag und Monat unbekannt	00.00.1966	Zeitraum: 1.1.1966 – 31.12.1966
Datum komplett unbekannt	00.00.0000	Zeitraum: nicht gesetzt (null)

Des Weiteren muss die Bibliothek die Eingabe unbekannter Datums- oder Zeitbestandteile mittels „x“ unterstützen. Diese Möglichkeit wird die Eingabe unbekannter Datums- oder Zeitbestandteile mittels Nullen mittelfristig ablösen. Die Eingabe mittels „x“ ermöglicht die oben genannten Sonderfälle auch für Zeitwerte, bei denen im Unterschied zu Datumswerten „0“ ein korrekter Wert für die jeweiligen Bestandteile (Stunde, Minute und Sekunde) ist. Eine Übersicht der so umgesetzten Spezialfälle zeigt Tabelle 10.

Tabelle 10. Umsetzung der Sonderfälle (mit „x“)
Sonderfall	Eingabe / Darstellung	Intern
Tag unbekannt	xx.05.1966	Zeitraum: 1.5.1966 – 31.5.1966
Tag und Monat unbekannt	xx.xx.1966	Zeitraum: 1.1.1966 – 31.12.1966
Datum komplett unbekannt	xx.xx.xxxx	Zeitraum: nicht gesetzt (null)
Sekunde unbekannt	14:34:xx	Zeitraum: 14:34:00 – 14:34:59
Sekunde und Minute unbekannt	14:xx:xx	Zeitraum: 14:00:00 – 14:59:59
Zeit komplett unbekannt	xx:xx:xx	Zeitraum: nicht gesetzt (null)

4.6. Testunterstützung

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!