chore(java): consolidate mss-failsafe to single canonical copy
Replace the stale multi-module java/mss-failsafe skeleton (old user-management prototype) with the active single-module machine-safety inspection app that was living in its own standalone repo at the repo root. - Remove old java/mss-failsafe/ multi-module tree (mss, userdata, userManagement, mssfailsafe.datalayer, mssfailsafeWeblayer) incl. committed build artifacts - Add the active app (PrimeFaces 11 / JSF 2.3 / Hibernate 5.6 / iText / POI) flattened into java/mss-failsafe/ as the only mss-failsafe in git - Working tree captured = master tip 2a142b5 + in-progress uncommitted work (incl. .github/*.instructions.md AI-context files) - Archive the standalone repo's 33-commit history in GIT_HISTORY_ARCHIVE.md since its .git was not migrated This is the source of truth / base for the upcoming upgraded rewrite.
This commit is contained in:
Patrick Plate
+97
@@ -0,0 +1,97 @@
|
||||
# Mechanismus: Refresh & Fake-ID
|
||||
|
||||
## Problemstellung
|
||||
Im UI werden häufig neue Objekte in Collections angezeigt, bevor sie persistiert sind. Diese benötigen eine temporäre Identifikation (ID) für Auswahl/Operationen, ohne den Datenbankzustand zu verfälschen.
|
||||
|
||||
## Fake-ID Strategie
|
||||
- Negative Long Werte (< 0) kennzeichnen nicht persistierte Objekte.
|
||||
- Erzeugung: `AbstractController.createFakeID(Collection<ENT>)`:
|
||||
- Startwert -1.
|
||||
- Falls bereits negative IDs existieren → Nimmt die kleinste negative und subtrahiert 1.
|
||||
- Ergebnis: Sequenz -1, -2, -3 ... (absteigend).
|
||||
|
||||
## Persistieren
|
||||
Vor finalem Speichern (z.B. `SecurityAreaController.save()`):
|
||||
1. Alle Entities mit `id < 0` → `setId(null)`.
|
||||
2. `AbstractManager.saveAll()` unterscheidet durch `entity.getId() == null` zwischen Persist und Merge.
|
||||
3. Datenbank vergibt positive ID (Auto Increment / Sequence).
|
||||
|
||||
## Vorteile
|
||||
- Klare Unterscheidung UI-temporär vs. persistent.
|
||||
- Verhindert versehentliches Auslösen von Merge bei noch nicht existierenden DB Zeilen.
|
||||
|
||||
## Risiken
|
||||
- Verwechslung negativ gesetzter IDs mit echten IDs (nicht möglich, da DB positive IDs generiert).
|
||||
- Direkte Verwendung negativer IDs in DB-Operationen (vermeiden: Prüfen auf `id > 0` vor `em.find`).
|
||||
|
||||
## Refresh
|
||||
- Methode `AbstractController.refrehSelected()` (Tippfehler im Namen, historisch) ruft `getManager().refresh(selected)`.
|
||||
- `AbstractManager.refresh(entity)`:
|
||||
- Falls ID null → `save(entity)` (persistiert neues Objekt).
|
||||
- `merge` für Managed Zustand und `Hibernate.initialize(entity)` zur Lazy Init.
|
||||
|
||||
## Best Practices
|
||||
- Nach komplexen Änderungen (Add/Remove Child Collections) Refresh durchführen wenn UI weitere Lazy Properties benötigt.
|
||||
- Beim Klonen persistenter Objekte zuerst DB-Laden → danach Kopie erstellen.
|
||||
|
||||
## Potentielle Verbesserungen
|
||||
- Korrektur Tippfehler `refrehSelected()` → `refreshSelected()` (Refactoring + Suchanpassungen).
|
||||
- Kennzeichnung Fake-ID generierender Methoden mit JavaDoc für Klarheit.
|
||||
|
||||
---
|
||||
Aktualisiert: 2025-10-20
|
||||
# MSS Failsafe – Developer Einstieg
|
||||
|
||||
Dieses Verzeichnis bündelt technische Instruktionsdateien zur schnelleren Einarbeitung und zur Unterstützung automatischer Code-Generierung.
|
||||
|
||||
## Quick Start
|
||||
1. Java Version: Quell-/Ziellevel im POM: 11 (Property 1.8 ist historisch, der Compiler-Plugin setzt auf 11). Nutze lokal JDK 11.
|
||||
2. Application Server: Java EE 8 kompatibel (z.B. Payara 5 / WildFly 20 / GlassFish 5). Dependencies `javax.*` statt `jakarta.*`.
|
||||
3. Build:
|
||||
```cmd
|
||||
mvn clean package
|
||||
```
|
||||
Ergebnis: `target/mss-1.0-SNAPSHOT.war`.
|
||||
4. Deployment: WAR in kompatiblen EE 8 Server einspielen. Konfiguriere Datenquelle `pu_person` (JPA Persistence Unit – siehe `@PersistenceContext(name = "pu_person")`).
|
||||
5. Logging: Log4j2 Konfiguration in `src/main/resources/log4j2.xml`.
|
||||
6. Frontend: JSF 2.3 + PrimeFaces 11 + PrimeFlex 2.0.
|
||||
|
||||
## Wichtigste Schichten
|
||||
- model: JPA Entities (`AbstractEntity` Basis – enthält ID).
|
||||
- business: `*Manager` Klassen (Stateless EJBs) kapseln CRUD + Fachlogik.
|
||||
- controller: View/Request/Session Scoped JSF Backing Beans (Interaktion UI ↔ Business Layer).
|
||||
- webapp: XHTML Seiten (JSF Components + PrimeFaces).
|
||||
- resources: Text-/Konfigurationsdateien, Checklisten.
|
||||
|
||||
## Kern-Patterns
|
||||
- Manager erben von `AbstractManager<T>` (generisches CRUD mit `save`, `saveAll`, `remove`, `refresh`).
|
||||
- Controller erben von `AbstractController<E>` (Message Handling, Fake-ID-Erzeugung für neue (noch nicht persistierte) Entities, PDF Hilfen, Auswahlzustand `selected/created`).
|
||||
- Negative IDs (< 0) werden als temporäre (noch nicht persistierte) Objekte verwendet – wichtig bei UI-Listen vor Sammel-Speichern.
|
||||
- Lazy Collections werden vor Nutzung mit `Hibernate.initialize(...)` initialisiert (Refresh/Reload Methoden).
|
||||
|
||||
## Erweiterung – Schnellanleitung
|
||||
1. Neue Entity anlegen (JPA @Entity, extends `AbstractEntity`).
|
||||
2. Manager erstellen: `@Stateless`, extends `AbstractManager<YourEntity>`, implementiert `getEntityManager()`. Zusätzliche Named Queries in Entity definieren.
|
||||
3. Controller erstellen: `@Named`, Scope festlegen (`@ViewScoped`, `@SessionScoped`, etc.), extends `AbstractController<YourEntity>`, injiziere Manager mit `@EJB`.
|
||||
4. XHTML Seite/Fragment erstellen und Controller referenzieren (`#{yourController}`) + PrimeFaces Komponenten.
|
||||
5. Tests (optional, derzeit kaum vorhanden) – vorschlagen: Architektur-Test + Manager CRUD Test.
|
||||
|
||||
## Fragebögen / Sicherheitsbereiche
|
||||
Ein ausführlicher Workflow liegt in `QUESTIONNAIRE_WORKFLOW.md` und `SECURITY_AREA_DOMAIN.md`.
|
||||
|
||||
## PDF-Erzeugung
|
||||
- Verwendet iText (5.x + 7.x Module). Utilities liegen in `AbstractController` (Tabellen, Kopfzeilen, Seitennummern).
|
||||
- Logo Pfad `LOGO_PATH = /rundata/logo.png` – stelle sicher, dass Datei beim Deployment verfügbar ist.
|
||||
|
||||
## Automatisierte Tools / AI Hinweise
|
||||
Siehe `AI_INSTRUCTIONS.md` für formatierte Kontextbereitstellung.
|
||||
|
||||
## Nächste Verbesserungen (Empfehlungen)
|
||||
- Konsolidierung auf iText7 (Legacy 5.x entfernen).
|
||||
- Einheitliche Exception-Strategie (momentan Logging + bool Rückgabe).
|
||||
- Mehr Unit Tests (Persistenz, Controller Interaktionen via Arquillian / Payara Micro).
|
||||
- Migrationspfad Richtung Jakarta EE 9+ (Namespace Wechsel).
|
||||
|
||||
---
|
||||
Letzte Aktualisierung: 2025-10-20
|
||||
|
||||
Reference in New Issue
Block a user