IPluginEntities

Inhalt [ Verbergen ]

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.

Wichtig! Stellen Sie keine harten Referenzen zwischen einer Plugin-Entität und einer Xima® Formcycle-Entität oder zwischen Entitäten verschiedener Plugins her. Eine harte Referenz zwischen zwei Entitäten wird durch eine Annotation wie OneToMany oder ManyToMany usw. hergestellt. Sie können jedoch Referenzen zwischen Entitäten eines einzelnen Entitäten-Plugins hinzufügen. Diese Einschränkung besteht, weil für jedes Plugin ein eigener EntityManager verwendet werden muss; und ein Entity-Manager weiß nicht, welche Entitäten einem anderen Entity-Manager zur Verfügung stehen. Wenn Sie Xima® Formcycle-Entitäten referenzieren müssen, sollten Sie die Verwendung von Soft-Referenzen in Betracht ziehen (d. h., Sie speichern einfach die IEntity.getId() oder IUUIDEntity.getUUID() einer Entität ohne Fremdschlüssel-Beschränkung). 

Beachten Sie auch, dass es möglich wäre, eine Fremdschlüssel-Beschränkung in der Datenbank zwischen einer Plugin-Entität und einer Xima® Formcycle-Entität hinzuzufügen. Dies wird offiziell nicht unterstützt und sollte vermieden werden, da es unnötige Abhängigkeiten schafft, die Plugin-Isolation verletzt, die Migration eines Entity-Plugins auf eine andere Datenbank erschwert und bei zukünftigen Updates von Xima® Formcycle kaputt gehen kann.

Anwendungsfälle

  • Speichern von Konfigurationsdaten durch ein Portal oder ein anderes Plugin 
  • Speichern von Elementen, die für eine Portalansicht benötigt werden

Wenn Sie sich dafür entscheiden, die Entitäten in der gleichen Datenbank zu speichern, die auch vom Xima® Formcycle-System verwendet wird, stellen Sie sicher, dass Sie eindeutige Namen verwenden, die nicht mit den von Xima® Formcycle verwendeten Namen in Konflikt stehen. Dazu gehören Tabellennamen, aber auch andere Namen wie Fremd- oder Primärschlüssel-Constraints sowie die ID für das Liquibase Changeset.

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());
}

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.