IPluginEntities
Schnittstelle IPluginEntities
Ein Beispiel für ein Entities-Plugin, das eine einzelne Entität namens ProgrammingLanguage hinzufügt. Auf der linken Seite sehen Sie die neue Datenbanktabelle, die in derselben Datenbank erstellt wurde, die auch von Xima® Formcycle verwendet wird. Auf der rechten Seite veranschaulicht ein einfaches Portal-Plugin, wie diese Entität verwendet werden kann. Die Portalseite zeigt eine Liste aller verfügbaren Programmiersprachen und lässt den Benutzer auch neue Sprachen erstellen.
Die Schnittstelle für ein Entity-Plugin. Mit dieser Art von Plugin können Sie benutzerdefinierte JPA (Java Persistence API) Entitäten zu Xima® Formcycle hinzufügen. Sie können diese Entitäten dann in anderen Plugins verwenden, wie z. B. IPluginPortal oder IPluginFormPreRender. Ein häufiger Anwendungsfall sind Portal-Plugins mit oder ohne IPluginMenuEntries, die Konfigurationsdaten oder eine Liste von Elementen in der Datenbank speichern müssen. Bitte beachten Sie, dass Plugin-Entities auf einem Frontend-Server nicht unterstützt werden - sie funktionieren nur auf einem Master-Server.
Jedes Entity-Plugin besteht aus den folgenden Komponenten:
- einer oder mehreren Entitätsklassen, die die Entity Annotation haben müssen
- einem Liquibase-Skript, das die erforderlichen Datenbanktabellen erstellt und für Updates verwendet werden kann, und
- eine DataSource mit den Verbindungsdetails zu einer Datenbank (standardmäßig die FORMCYCLE-Datenbank)
Die Entitätsklassen werden automatisch übernommen, sofern sie mit der Annotation Entity versehen sind.
Anwendungsfälle
- Speichern von Konfigurationsdaten durch ein Portal oder ein anderes Plugin
- Speichern von Elementen, die für eine Portalansicht benötigt werden
Methodensignaturen
default IPluginEntitiesConnectionRetVal getConnectionDetails()
Standardmäßig werden Plugin-Entitäten in der Systemdatenbank gespeichert, d.h. in der gleichen Datenbank, die auch Xima® Formcycle verwendet. Stellen Sie in diesem Fall sicher, dass die Tabellennamen für die Plugin-Entitäten nicht mit bereits vorhandenen Xima® Formcycle-Tabellennamen kollidieren. Wir empfehlen Ihnen, jedem Tabellennamen ein eigenes Präfix hinzuzufügen.
Falls erforderlich, können Sie diese Methode überschreiben und benutzerdefinierte Verbindungsdetails zurückgeben, um eine Verbindung zu einer anderen Datenbank herzustellen, in der Sie die Plugin-Entitäten speichern möchten.
- Rückgabewert
- Die Verbindungsdetails zu der Datenbank, in der die Plugin-Entitäten gespeichert werden sollen. Wenn null, wird die Systemdatenbank von Xima® Formcycle verwendet.
default List<String> getLiquibaseScripts()
Diese Methode kann verwendet werden, um eine Liste von Liquibase-Skripten zur Initialisierung oder Aktualisierung der Datenbank zurückzugeben. Die Liquibase-Skripte werden in der Reihenfolge ausgeführt, wie sie von dieser Methode zurückgegeben werden. Ein Liquibase-Skript besteht aus einer Liste von Change-Sets. Jedes Changeset ist für eine einzelne logische Datenbankänderung verantwortlich, z. B. das Erstellen einer Tabelle oder das Hinzufügen einiger neuer Spalten zu einer Tabelle. Wenn eine leere Liste zurückgegeben wird, wird kein Liquibase-Skript ausgeführt.
Wenn das Plugin zum ersten Mal installiert wird, werden die Skripte ausgeführt, um die anfängliche Datenbankkonfiguration zu erstellen. Wenn dieses Plugin dann auf eine neue Version aktualisiert wird und Sie auch die Datenbank aktualisieren müssen, können Sie dem Liquibase-Skript zusätzliche Änderungssätze hinzufügen. Alle Änderungssätze, die bereits ausgeführt wurden, werden nicht erneut ausgeführt. Damit dies funktioniert, stellen Sie sicher, dass Sie keine bestehenden Change Sets verändern, da Liquibase einen Hash des Quellcodes jedes Change Sets erstellt.
In einigen Fällen kann Ihre Datenbankeinrichtung von der Version von Xima® Formcycle abhängen. Wenn dies der Fall ist und Sie bestimmte Liquibase-Skripte nur für bestimmte Versionen ausführen möchten, können Sie über VersionsInfo#sdkVersion überprüfen, welche Version von Xima® Formcycle aktuell installiert ist.
Weitere Informationen finden Sie auf den Dokumentationsseiten von Liquibase.
- Rückgabewert
- Eine Liste von Liquibase-Skripten zum Initialisieren oder Aktualisieren der Datenbank. Kann eine leere Liste sein, falls Sie die Datenbank einrichten müssen. Jeder Eintrag muss ein Pfad zu einer Liquibase-XML-Datei sein, in dem Format, das von ClassLoader#getResources akzeptiert wird.
void onDatabaseReady(IPluginEntitiesParams params) throws FCPluginException
Diese Callback-Methode wird aufgerufen, nachdem das Plugin initialisiert wurde und nachdem die Datenbank eingerichtet wurde und bereit ist, verwendet zu werden. Sie können die EntityManagerFactory, die an diese Methode übergeben wird, verwenden, um neue Entitäten zu erstellen oder bestehende zu holen, zu aktualisieren und zu löschen. Dies geschieht normalerweise durch Anlegen eines neuen EntityManager über EntityManagerFactory#createEntityManager.
Es kann jedoch sein, dass die vom EntityManager angebotene API für Sie schwer zu bedienen ist. In diesem Fall können Sie die von Xima® Formcycle bereitgestellte DAO (Database Access Objects)-API verwenden, um einfacher mit Ihren Entitäten zu arbeiten. Verwenden Sie zunächst IPluginEntitiesParams#getPluginEmManager und speichern Sie den EM-Manager in einem statischen Feld zur späteren Verwendung in einer Bean oder einem Filter. Wenn Sie später auf die Datenbank zugreifen müssen, verwenden Sie IPluginEmManager#newEntityContext, um einen neuen Entity-Kontext zu erstellen und diesen Kontext an die von IAbstractDao angebotenen Methoden zu übergeben. Zum Beispiel, wenn Sie eine Entitätsklasse MyEntity haben und eine Liste aller Entitäten abrufen wollen:
try (final IBaseEntityContext ec = pluginEmManager.newEntityContext()) {
// Entitätskontext mit einem DAO verwenden
// dies holt alle vorhandenen MyEntity
new AbstractDao(MyEntity.class) {}.all(null, new QueryCriteriaManager());
}
// Entitätskontext mit einem DAO verwenden
// dies holt alle vorhandenen MyEntity
new AbstractDao(MyEntity.class) {}.all(null, new QueryCriteriaManager());
}
Wenn Sie nur eine Teilmenge von Entitäten abrufen wollen, die einem bestimmten Kriterium entsprechen, verwenden Sie die QueryCriteriaManager API, die von Xima® Formcycle angeboten wird. Und schließlich können Sie, anstatt ein neues DAO zu erstellen, Ihre eigenen DAO-Klassen erstellen, indem Sie IAbstractDao erweitern.
- Parameter
- Diese Methode nimmt die folgenden Parameter entgegen:
- params
- Die Parameter, von denen diese Methode Gebrauch machen kann. Enthält die EntityManagerFactory für die Arbeit mit den Entitäten, sowie den IPluginEmManager, um diese Arbeit zu erleichtern.
- Throws
- Diese Methode darf die folgenden Exceptions werfen:
- FCPluginException
- Wenn diese Methode eine Ersteinrichtung durchführt, z. B. das Erstellen neuer Entitäten, und diese Einrichtung fehlschlägt. Wenn diese Ausnahme ausgelöst wird, wird dieses Plugin deaktiviert und nicht in Betrieb genommen.