Namenskonventionen

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.

1. Einleitung

Die umfassenden Konzepte der IsyFact automatisieren und vereinheitlichen den Bau von Anwendungen. Um dies zu erreichen ist es wichtig, dass Namen und Benennungen über die gesamte Anwendungslandschaft hinweg einheitlich sind. Es existiert daher eine Vielzahl von Namenskonventionen in den verschiedenen Konzepten der IsyFact. Dieses Dokument ist Teil der IsyFact Standards.

1.1. Kurzüberblick

Dieses Dokument sammelt die Namenskonventionen der IsyFact an einem zentralen Ort. In den jeweiligen Konzepten wird die Vorgabe nochmals erwähnt.

Nach der Einleitung, die einen kurzen Abschnitt über generelle Anforderungen an Namen enthält, befasst sich das Kapitel Namenskonventionen mit den Namenskonventionen der IsyFact. Es ist dabei unterteilt in allgemeine Konventionen sowie Konventionen in der Entwicklung von Anwendungen.

Jede Namenskonvention ist in Tabellenform dargestellt. Es ist jeweils das Namensschema der Konvention mit Beispielen zu sehen. Ergänzt wird diese Darstellung durch eine Erklärung der genutzten Variablen und ihrer möglichen Ausprägungen.

2. Namenskonventionen

Dieser Abschnitt beschreibt die Namenskonventionen der IsyFact. In komplexen Anwendungslandschaften werden Anwendungen in der Regel in funktionale Kategorien eingeordnet und typisiert (z.B. Register und Geschäftsanwendungen). Bei weniger komplexen Kontexten, in denen nur eine einzige oder wenige Geschäftsanwendungen existieren, wird meist allgemein von „Geschäftsanwendungen“ gesprochen.

In folgenden Vorgaben wird daher zwischen Geschäftsanwendungen und Registern unterschieden. Für andere Kontexte können weitere Systemtypen eingeführt werden, für die entsprechende Vorgaben nach dem gleichen Schema zu definieren sind.

2.1. Allgemein

In diesem Abschnitt werden allgemeine Namenskonventionen festgehalten.

2.1.1. Namen von Anwendungen

Je nach Anwendungstyp ist der Name unterschiedlich zu wählen. Die verschiedenen Varianten sind wie folgt abgebildet.

2.1.1.1. Geschäftsanwendung

Tabelle 1. Schema für eine Geschäftsanwendung
Name einer Geschäftsanwendung
Schema	`<verfahren> Geschäftsanwendung`
Beispiele	`Xyz Geschäftsanwendung`
Variable	Mögliche Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.

2.1.1.2. Register

Tabelle 2. Schema für ein Register
Name eines Registers
Schema	`<verfahren> Register`
Beispiele	`Xyz Register`
Variable	Erklärung / Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.

2.2. Spezifikation

In diesem Kapitel werden die Namenskonventionen der Spezifikation festgehalten. Sie sind vor allem der Vorlage zur Systemspezifikation entnommen.

2.2.1. Geschäftsprozess

Tabelle 3. Geschäftsprozess
Geschäftsprozess
Schema	`GEP_<geschäftsprozessname>`
Beispiele	`GEP_Akte_Suchen`

2.2.2. Geschäftsvorfall

Tabelle 4. Geschäftsvorfall
Geschäftsvorfall
Schema	`GVF_<geschäftsvorfallname>`
Beispiele	`GVF_Akte_Suchen`

2.2.3. Aktivität

Tabelle 5. Aktivität
Aktivität
Schema	`AKT_<aktivitätsname>`
Beispiele	`AKT_Akte_Suchen`

2.2.4. Dokument

Tabelle 6. Dokument
Dokument
Schema	`DOK_<dokumentname>`
Beispiele	`DOK_Spezifikationsvorlage_Test`

2.2.5. Persistente Daten

Tabelle 7. Persistente Daten
Persistente Daten
Schema	`DAT_<datenbestandsname>`
Beispiele	`DAT_Akte_Suche`

2.2.6. Organisationseinheit

Tabelle 8. Organisationseinheit
Organistationseinheit
Schema	`ORG_<organisationsheit>`
Beispiele	`ORG_Abteilung_Xyz`

2.2.7. Anwendung

Tabelle 9. Anwendung
Anwendung
Schema	`SYS_<anwendung>`
Beispiele	`SYS_Register_Xyz`

2.2.8. Anwendungskomponente

Tabelle 10. Anwendungskomponente
Anwendungskomponente
Schema	`ANK_<anwendungskomponente>`
Beispiele	`ANK_Meldung_Beispiel`

2.2.9. Anwendungsfall

Tabelle 11. Anwendungsfall
Anwendungsfall
Schema	`AWF_<anwendungsfallname>`
Beispiele	`AWF_Meldung_Durchfuehren`

2.2.10. Anwendungsfunktion

Tabelle 12. Anwendungsfunktion
Anwendungsfunktion
Schema	`AFU_<anwendungsfunktionsname>`
Beispiele	`AFU_Wert_Berechnen`

2.2.11. Batch

Tabelle 13. Batch
Batch
Schema	`BAT_<batch>`
Beispiele	`BAT_Bereinigungslauf_Durchfuehren`

2.2.12. Modellkomponente

Tabelle 14. Modellkomponente
Modellkomponente
Schema	`MKO_<modellkomponente>`
Beispiele	`MKO_Aktenverwaltung`

2.2.13. Entität

Tabelle 15. Entität
Entität
Schema	`ETY_<entität>`
Beispiele	`ETY_Akte`

2.2.14. Dialog

Tabelle 16. Dialog
Dialog
Schema	`DIA_<dialogname>`
Beispiele	`DIA_Akten_Suche`

2.2.15. Maske

Tabelle 17. Maske
Maske
Schema	`MAS_<maskenname>`
Beispiele	`MAS_Treffer_Anzeige`

2.2.16. Druckstück

Tabelle 18. Druckstück
Druckstück
Schema	`DRU_<druckstückname>`
Beispiele	`DRU_Akten_Suchergebnis`

2.2.17. Nachbarschnittstelle

Tabelle 19. Nachbarschnittstelle
Nachbarschnittstelle
Schema	`NST_<schnittstellenname>`
Beispiele	`NST_Meldung`

2.2.18. Schnittstellenentitätstyp

Tabelle 20. Schnittstellenentitätstyp
Schnittstellenentitätstyp
Schema	`NSE_<entitaetstyp>`
Beispiele	`NSE_Personen_Suche`

2.2.19. Nicht-Funktionale Anforderung

Tabelle 21. Nicht-Funktionale Anforderung
Nicht-Funktionale Anforderung
Schema	`NFA_<anforderungsname>`
Beispiele	`NFA_Durchsatz_Pro_Minute`

2.3. Entwicklung

Dieser Abschnitt fasst die Namenskonventionen zusammen, die bei der Entwicklung einer Anwendung nach IsyFact relevant sind. Das sind vor allem Klassen- und Dateinamen.

Einige der hier genannten Namenskonventionen sind von denen der Spezifikation abhängig, beziehungsweise werden davon abgeleitet.

2.3.1. Maven-Artefakte und -Module

Tabelle 22. Group-ID von Modulen/Artefakten
Group-ID von Maven-Modulen/-Artefakten
Schema Group-ID	`<sprach-kürzel>.<organisation>.<firma>.<domäne>`
Beispiel	`de.bund.bva.isyfact`

Tabelle 23. Artefakt-ID von Maven-Modulen/-Artefakten
Artefakt-ID von Maven-Modulen/-Artefakten
Schema Artefakt-ID	`<präfix>-<funktion/komponente>` `<präfix>-<funktion/komponente>-<teilkomponente>`
Beispiel	`isy-documentation` `isy-documentation-core`

Besteht der Zweck genau einer Klasse ausschließlich oder zum größten Teil aus der Implementierung eines Interfaces, dann wird die Klasse so genannt wie das Interface, ergänzt um das Suffix Impl.

Tabelle 24. Klassenname bei hauptsächlicher Implementierung eines Interfaces
Klassenname bei hauptsächlicher Implementierung eines Interfaces
Schema	`<Interface>Impl`
Beispiele	`MeldungImpl` `NachrichtErzeugungImpl`

2.3.2. Technische Systemnamen

Inhalt in Überarbeitung

Die folgenden Inhalte können sich ohne Ankündigung bis zum nächsten Release umfassend ändern.

Die überarbeiteten Inhalte sind möglicherweise noch nicht in der gesamten IsyFact berücksichtigt, sodass es während der Überarbeitung zu Inkonsistenzen in der Dokumentation kommen kann.

Die technischen Systemnamen entsprechen der technischen Bezeichnung für eine IsyFact-konforme Anwendung. Sie werden unter anderem für Projektnamen in Eclipse, Dokument Basis / Context Root bei Schnittstellen-URLs und als Namen von Deployment-Einheiten (vgl. Kapitel RPM-Pakete) verwendet.

2.3.2.1. Geschäftsanwendung

Tabelle 25. Name einer Geschäftsanwendung
Name einer Geschäftsanwendung
Schema	`<verfahren>-gk`
Beispiele	`xyz-gk`
Variable	Mögliche Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.

2.3.2.2. Register

Tabelle 26. Name eines Registers
Name eines Registers
Schema	`<verfahren>-register`
Beispiele	`xyz-register`
Variable	Erklärung / Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.

2.3.2.3. Servicegateway

Tabelle 27. Name eines Servicegateways
Name eines Servicegateways
Schemata	`<verfahren>-sgw` `<verfahren>-<zielverfahren>-sgw`
Beispiele	`xyz-sgw` `xyz-dienstabc-sgw`
Variable	Mögliche Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.
`<zielverfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs, mit dem dieser SGW kommuniziert bzw. für den er eine Schnittstelle bereitstellt.

2.3.2.4. Mailgateway

Tabelle 28. Name eines Mailgateways
Name eines Mailgateways
Schema	`<verfahren>-mailgw`
Beispiele	`xyz-mailgw`
Variable	Mögliche Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.

2.3.2.5. Querschnittsanwendung

Tabelle 29. Name einer Querschnittsanwendung
Name einer Querschnittsanwendung
Schema	`<verfahren>-qk`
Beispiele	`xyz-qk`
Variable	Mögliche Ausprägungen
`<verfahren>`	Der (Kurz)name des Verfahrens/Anwendungsbereichs.

2.3.2.6. Auslagern einer Fachkomponente aus einer Geschäftsanwendung

Wenn eine Geschäftsanwendung in mehrere Fachkomponenten getrennt wird, dann wird die herausgebildete Fachkomponente wie folgt genannt:

Tabelle 30. Name einer ausgelagerten fachlichen Geschäftskomponente
Name einer fachlichen Geschäftskomponente
Schema	`<anwendungsname>-<fachlichkeit>-gk`
Beispiele	`xyz-fach1-gk` `xyz-fach1-register`
Variable	Mögliche Ausprägungen
`<anwendungsname>`	Der Name einer Anwendung, wie in den vorigen Abschnitten beschrieben. Er setzt sich meistens aus einem Systemkürzel und dem Systemtyp zusammen.
`<fachlichkeit>`	Der Name der Fachkomponente, welche aus der Geschäftsanwendung ausgelagert wird.

2.3.2.7. Auslagern einer technischen Komponente aus einer Anwendung

Wenn eine Geschäftsanwendung oder Fachkomponente technisch in mehrere IT-Systeme getrennt wird, dann werden diese Systeme wie folgt genannt:

Tabelle 31. Name einer ausgelagerten technischen Geschäftskomponente
Name einer technischen Geschäftskomponente
Schema	`<anwendungsname>-<fachlichkeit>-gk<komponente>`
Beispiele	`xyz-fach1-gkgui` `xyz-qkbatch`
Variable	Mögliche Ausprägungen
`<anwendungsname>`	Der Name einer Anwendung, wie in den vorigen Abschnitten beschrieben. Er setzt sich meistens aus einem Systemkürzel und dem Systemtyp zusammen.
`<fachlichkeit>`	Der Name der Fachkomponente, welche aus der Geschäftsanwendung ausgelagert wird.
`<komponente>`	Der Name der technischen Komponente: meist `gui` für eine ausgelagerte grafische Oberfläche oder `batch` für einen ausgelagerten Batch.

2.3.3. Name der Web Application

Der Name einer Web-Applikation (Webapp-Root) ist immer gleich dem technischen Systemnamen.

2.3.4. Persistenzschicht

Tabelle 32. Namenskonvention DAO: Spring Data Repository
Data Access Object: Spring Data Repository
Schema	`<Entität>Repository`
Beispiel	`MyEntityRepository`

Der Name eines Datenbankschemas genügt den folgenden Anforderungen:

er enthält vollständige, beschreibende, aussprechbare Namen (oder bekannte Abkürzungen),
er muss mit einem Buchstaben beginnen,
nur Buchstaben, Zahlen und Unterstriche (_) sind erlaubt,
Umlaute, Sonderzeichen, Bindestriche und Leerzeichen sind nicht erlaubt.

Tabelle 33. Vorgaben zur Paketstruktur für Klassen der Persistenzschicht
Klassen	Package
DAO	`<organisation>.<domäne>.<system>.persistence.<komponente>.dao`
Entity	`<organisation>.<domäne>.<system>.persistence.<komponente>.entity`

2.3.4.1. Historisierung

Tabelle 34. DAO-Erweiterung (Bearbeitungshistorie): Lesen der zum Datum gültigen Entität
Schema	<Entity> lese<Entity>(<Schlüssel>, Calendar)`
Beispiel	`AkteDao leseAkte(id, Calendar)`

Tabelle 35. DAO-Erweiterung (Bearbeitungshistorie): Lesen der aktuell gültigen Entität
Schema	<Entity> lese<Entity>(<Schlüssel>)`
Beispiel	`AkteDao leseAkte(id)`

Tabelle 36. DAO-Erweiterung (Bearbeitungshistorie): Lesen der gesamten Historie einer Entität
Schema	`List<Entität> lese<Entität>Historie(Schlüssel)`
Beispiel	`List<AkteDao> leseAkteHistorie(id)`

Tabelle 37. DAO-Erweiterung (Bearbeitungshistorie): Erzeugen einer neuen Version einer Entität
Schema	`Entität erzeugeNeueVersion(Entität)`
Beispiel	`AkteDao erzeugeNeueVersion(Akte)`

Tabelle 38. DAO-Erweiterung (Bearbeitungshistorie): Setzen einer maximalen Anzahl von Versionen
Schema	`MAX_EINTRAEGE_HISTORIE`

2.4. Anwendungskern

Tabelle 39. Namenskonvention Geschäftsobjekt
Geschäftsobjekt
Schema	`<Entitaetsname>Bo`
Beispiel	`AkteBo`

Tabelle 40. Namenskonvention Anwendungsfallklassen
Anwendungsfallklassen
Schema	`Awf<Anwendungsfall>`
Beispiele	`AwfAntragVerarbeiten` `AwfEntscheidungDurchfuehren`

Tabelle 41. Namenskonvention Anwendungsfunktion
Anwendungsfunktion
Schema	`Afu<Anwendungsfunktion>`
Beispiele	`AfuBerechnungFristdatum` `AfuErmittlungEntscheidungsrelevanz`

2.5. Batchrahmen

Tabelle 42. Batches: Konfigurationsparameter Kommandozeile
Batches: Konfigurationsparameter Kommandozeile
Schema	`-<Parametername> <Parameterwert>`
Beispiele	`-laufzeit 10`

Tabelle 43. Batches: Benennung Konfigurationsdateien
Batches: Benennung Konfigurationsdateien (unter resources/resources/batch)
Schemata	`<name-des-batches>.properties`
Beispiele	`loeschfrist-pruefen.properties import-bhknz-liste.properties`

Tabelle 44. Batches: Konfigurationsparameter Konfigurationsdatei
Batches: Konfigurationsparameter Konfigurationsdatei
Schema	`<Parametername>=<Parameterwert> <Parametername>.<Parametername>=<Parameterwert>`
Beispiele	`BatchName=LoeschBatch Loeschfunktion.DatumVon=30.11.2019`

Analog zu den Anwendungsfällen werden Batch-Klassen mit dem Präfix Bat gekennzeichnet.

Tabelle 45. Batches: Klassen
Batches: Klassen
Schema	`Bat<Batchname>`
Beispiele	`BatLoeschfristPruefen BatSendenAllerInformationen`

2.6. REST-Schnittstellen

Tabelle 46. Namenskonvention prozessorientierter URIs
Prozessorientierte URIs
Schema	`/{geschaeftsvorfall}/{geschaeftsprozess}`
Beispiele	`/auskunft/personaliensuche` `/auskunft/dokumentensuche` `/auskunft/schluesselsuche` `/meldung/erstmeldung` `/meldung/aenderung`

Tabelle 47. Namenskonvention Ressourcen-URIs
Ressourcen-URIs
Schema	`/{ressource}/{id}/{ressource}/{id}/{...}`
Regeln	Die Bezeichnung der Ressource beinhaltet ausschließlich Kleinbuchstaben. Zwischen Teilen zusammengesetzter Begriffe steht jeweils ein Bindestrich. Beinhaltet die Bezeichnung Sonderzeichen, müssen sie gemäß üblicher Transkriptionsregeln ersetzt werden (z. B. "ae" statt "ä").
Beispiele	`/kunden/12345/bestellungen/123/artikel` `/nachrichten` Beispiele für eine Menge von Objekten. Die Ressource liefert alle Objekte zurück. `/nachrichten/{id}` Beispiel für ein einzelnes Objekt. Die Ressource liefert ein eindeutig identifizierbares Objekt zurück. `/eingehende-nachrichten/` Beispiel für zusammengesetzte Begriffe. `/vertraege/` Beispiel für die Ersetzung von Sonderzeichen.

Tabelle 48. Namenskonvention Beziehungen zwischen Ressourcen
Beziehungen zwischen Ressourcen
Schema	`/{ressourcen A}/{id von einer Ressource A}/{ressource(n) B}/{...}`
Hinweis	Enthält eine Ressource wiederum mehrere Ressourcen, wird wieder der Plural verwendet.
Beispiele	`/nachrichten/{id}/absender` adressiert den Absender einer bestimmten Nachricht. `/nachrichten/{id_n}/cc/{id_e}` adressiert den bestimmten CC-Empfänger (mit der Id `id_e`) einer bestimmten Nachricht (mit der Id `id_n`).

Tabelle 49. Namenskonvention Adressierung von mehreren Ressourcen
Adressierung von mehreren Ressourcen
Schema	`/{ressourcen}/{id1},{id2}`
Beispiele	`/nachrichten/{id1},{id2}`

2.7. Deployment/Betrieb von Anwendungen

2.7.1. RPM-Pakete

Für die Benennung von RPM-Paketen existiert eine Konvention, welche durch den RPM-Standard vorgeben wird.

Siehe RPM Packaging Guide

Tabelle 50. RPM-Pakete
RPM-Pakete
Schema	`<paketname>-<versionsnummer>-<build-version>.<architektur>.rpm`
Beispiele	`isy-geschaeftsanwendung-batch-1.2.0-01.noarch.rpm`
Variable	Mögliche Ausprägungen
`<paketname>`	Name der Deployment-Einheit. Setzt sich in der Regel aus einem Präfix für die Anwendungslandschaft (<awl>) und dem Anwendungsnamen (siehe Kapitel 2.1.1) zusammen. Deployment-Einheiten der Anwendungslandschaft IsyFact besitzen z.B. das Präfix „isy“. Beispiel: `<awl>-fachanwendung-gk-…` `<awl>-fachanwendung-gkbatch-…`
`<versionsnummer>`	Versionsnummer der Deployment-Einheit, z.B. „1.2.0“. Die Versionierung basiert auf Semantic Versioning und ist im Konzept IsyFact Versionierung beschrieben.
`<build-version>`	Hier wird die Build-Nummer eingesetzt. Sie wird bei dem Bau jeder Auslieferungsversion (insbesondere auch bei Nachlieferungen) erhöht. Während der Entwicklung (Continuous Integration) wird hier eine laufende Nummer (Revisionsnummer der Versionsverwaltung, laufende Build-Nummer des CI-Servers etc.) eingesetzt.
`<architektur>`	Gibt die Systemarchitektur an, für welche das Paket erstellt wurde. Da IsyFact-konforme Anwendungen in Java erstellt werden, wird hier immer „noarch“ eingesetzt. Sollten Anwendungen Architektur-spezifische Bestandteile enthalten, wird hier die vom RPM-Standard vorgegebene Architektur-Bezeichnung eingesetzt.

2.7.2. Installationspfade

Die Installationspfade sind im Systemhandbuch beschrieben.

Tabelle 51. Installationspfade – Anwendung
Installationspfade – Anwendung
Schema	`/opt/<rpm-paketname> (Anwendungsbasis)` `/opt/<rpm-paketname>/bin (Skript-Verzeichnis)` `/opt/<rpm-paketname>/tomcat (Tomcat)` `/opt/<rpm-paketname>/tomcat/webapps/<name> (Basis der Webapp)`
Beispiele	`/opt/isy-xyz-anwendung` `/opt/isy-xyz-anwendung/bin` `/opt/isy-xyz-anwendung/tomcat` `/opt/isy-xyz-anwendung/tomcat/webapp/xyz-anwendung`
Installationspfade: Logdateien
Schema	`/var/log/<rpm-paketname>`
Beispiele	`/var/log/isy-xyz-anwendung`
Installationspfade: Betriebliche Konfiguration
Schema	`/etc/<rpm-paketname>`
Beispiele	`/etc/isy-xyz-anwendung`

2.8. Dokumentation

Die Namenskonventionen für die Dokumentation sind Teil des Leitfadens Dokumentation.