Plugin-Entwicklerhandbuch

Ziel

Dieses Handbuch beschreibt den vollständigen Weg von der Plugin-Idee bis zur sicheren Bereitstellung in der Enterprise PDF Toolbox.

Entwicklungsablauf

1. Capability und fachlichen Vertrag festlegen.
2. Abhängigkeit ausschließlich auf das öffentliche pdf-tool-plugin-sdk setzen.
3. Plugin-Manifest mit ID, Version, API-Kompatibilität, Capabilities und Berechtigungen pflegen.
4. Implementierung über Ports und Adapter kapseln.
5. Eingaben validieren und Ressourcenlimits beachten.
6. Unit-, Vertrags- und Integrationsprüfungen ausführen.
7. Plugin-JAR und Manifest gemeinsam paketieren.
8. Installation zunächst in einer isolierten Testumgebung prüfen.

Minimale Struktur

my-plugin/
├── pom.xml
├── src/main/java/…/MyPlugin.java
├── src/main/resources/META-INF/pdf-tool-plugin.json
└── src/test/java/…/MyPluginContractTest.java

Maven-Abhängigkeit

<dependency>
  <groupId>com.example.pdftool</groupId>
  <artifactId>pdf-tool-plugin-sdk</artifactId>
  <version>5.12.1</version>
  <scope>provided</scope>
</dependency>

Zentrale Regeln

• Keine Abhängigkeit auf interne Web-, Persistence- oder PDFBox-Implementierungen.
• Capability-IDs stabil und eindeutig halten.
• Netzwerk-, Dateisystem- und Prozesszugriffe nur bei expliziter Manifest-Berechtigung.
• Keine Zugangsdaten, privaten Schlüssel oder lokalen Pfade im Plugin-Artefakt speichern.
• Große Dokumente streamen; keine unkontrollierten byte[]-Kopien.
• Fehler über stabile Fehlercodes und verständliche Meldungen ausgeben.
• Abbruchsignale, Zeitlimits und Mandantengrenzen beachten.

Manifest

Das Manifest beschreibt mindestens Plugin-ID, Anzeigename, Version, benötigte SDK-Version, bereitgestellte Capabilities und angeforderte Berechtigungen. Unbekannte oder überbreite Berechtigungen müssen von der Plugin-Validierung abgelehnt werden.

Entwurfsmuster

• Plugin Pattern: Erweiterung ohne Änderung des Anwendungskerns.
• Ports and Adapters: Trennung zwischen Vertrag und technischer Bibliothek.
• Factory Method: kontrollierte Erzeugung von Plugin-Komponenten.
• Strategy Pattern: auswählbare Capability-Implementierung.
• Security Gateway: zentrale Prüfung aller angeforderten Berechtigungen.

Tests

Mindestens erforderlich sind Manifestvalidierung, SDK-Vertragstest, Capability-Erkennung, negative Berechtigungstests, Ressourcenlimitprüfung und ein isolierter Smoke-Test. Das vorhandene Beispielplugin dient als ausführbare Referenz.

Paketierung und Veröffentlichung

Das Ergebnis besteht aus einem reproduzierbaren Plugin-JAR, dem eingebetteten Manifest, Prüfsummen und einer kurzen README. Vor Freigabe müssen Lizenz- und Abhängigkeitsprüfung, Signatur beziehungsweise Prüfsumme und Kompatibilität mit der Zielversion dokumentiert werden.

Migration

Breaking Changes am öffentlichen SDK benötigen eine neue Hauptversion, Migrationshinweise und eine Übergangsfrist. Erweiterungen sollen bevorzugt über neue optionale Schnittstellen oder Default-Methoden erfolgen.