pi_mcps/java/mss-failsafe/docs/HOWTO_EXTEND.md

How-To: Projekt erweitern

Neuer Fachbereich (Beispiel: InspectionReport)

1. Entity anlegen

• Paket: model.report.
• Klasse: InspectionReport extends AbstractEntity.
• Felder: date, inspector, machine, remarks.
• Named Queries definieren (z.B. FIND_BY_MACHINE).

2. Manager

@Stateless
@Named
public class InspectionReportManager extends AbstractManager<InspectionReport> {
    @PersistenceContext(name = "pu_person")
    EntityManager em;
    public InspectionReportManager() { super(InspectionReport.class); }
    @Override protected EntityManager getEntityManager() { return em; }
    // Fachmethoden: findByMachine(Long id)
}

3. Controller

@ViewScoped
@Named
public class InspectionReportController extends AbstractController<InspectionReport> {
    @EJB InspectionReportManager reportManager;
    @Inject MachineController machineController;
    public InspectionReportController() { setSelected(new InspectionReport()); setCreated(new InspectionReport()); }
    @Override protected AbstractManager<InspectionReport> getManager() { return reportManager; }
    @Override public void clearEntries() { setSelected(new InspectionReport()); setCreated(new InspectionReport()); getEntities().clear(); }
    public void saveReport(){ reportManager.save(getSelected()); successMessage(); }
}

4. UI Seite

• Pfad: webapp/report/inspection.xhtml.
• Binding: #{inspectionReportController}.
• Komponenten: Formular für Felder + Speichern Button.

5. Navigation

• Menüeintrag in globaler Navigationsstruktur (Tree oder Topbar) – analog createMachineMenu() Ansatz.

6. Tests

• Persistenz Test: Speichern + Laden.
• Manager Fachmethode Test.

Erweiterung vorhandener Funktionalität

• Beispiel: Neue PDF Sektion → Ergänze Hilfsmethode in AbstractController (sofern allgemein). Falls spezifisch für eine Domäne, eher Hilfsklasse im Domain-Paket.

Konsistenz-Checkliste

• Entity extends AbstractEntity
• Manager extends AbstractManager
• Controller extends AbstractController
• Negative IDs für neue Objekte vor Persist (falls in Listen)
• Internationale Zeichen (UTF-8) – POM setzt Encoding
• Logging bei Fehlern

Deployment Hinweise

• Sicherstellen, dass neue Named Queries beim Serverstart verfügbar (Entity korrekt gescannt).
• Falls neue Ressourcen (Logos, Templates) → in resources pflegen.

Typische Stolpersteine

• LazyInitializationException: Lösung refresh(entity) oder explizite Initialisierung im Manager.
• Doppelte Referenzen beim Klonen: IDs auf null setzen.
• Fehlende Transaktion: Sicherstellen @Transactional oder EJB Standard.

---

Aktualisiert: 2025-10-20