public interface IPluginEntities extends IFCPlugin
Entitys
to FORMCYCLE. You can then use these entities within other plugins, such as IPluginPortal or
IPluginFormPreRender. One common use case are portal plugins (with or without IPluginMenuEntries)
that need to save configuration data or a list of items in the database. Please note that plugin entities are not
supported on a FrontendServer. They will work only on a master server.
Each entities plugin consists of the following components:
Entity annotationDataSource with the connection details to a database (defaults to the FORMCYCLE database)Entity annotation.
Important: Do not set up any hard references between a plugin entity and a FORMCYCLE entity, or between entities
of different plugins. A hard reference between two entities is established by an annotation such as
OneToMany or ManyToMany etc. You can, however, add references between entities of a single entities
plugin. This limitation exists because a separate EntityManager needs to be used for each plugin; and an
entity manager does not know about the entities available to another entity manager. If you need to reference
FORMCYCLE entities, considers using soft references (eg just saving the IEntity.getId() or
IUUIDEntity.getUUID() of an entity without a foreign key constraint).
Also, note that it would be possible to add a foreign key constraint in the database between a plugin entity and a FORMCYCLE entity. This is not officially supported and should be avoided as it creates unnecessary dependencies, violates plugin isolation, makes it harder to migrate an entities plugin to a different database, and may break with future updates of FORMCYCLE.
CONFIG_FILENAMEATTR_NAME, COL_NAMEATTR_DISPLAY_NAME| Modifier and Type | Method and Description |
|---|---|
default IPluginEntitiesConnectionRetVal |
getConnectionDetails()
By default, plugin entities are saved in the system database, ie the same database that FORMCYCLE uses.
|
default List<String> |
getLiquibaseScripts()
This method may be used to return a list of Liquibase scripts for initializing or updating the database.
|
void |
onDatabaseReady(IPluginEntitiesParams params)
This callback method is invoked after the plugin was initialized
(
IFCPlugin.initialize(de.xima.fc.interfaces.plugin.lifecycle.IPluginInitializeData)) and after the database was set
up and is ready to be used. |
getDescription, getDescription, getDisplayName, getName, initialize, initPlugin, install, shutdown, shutdown, uninstalldefault IPluginEntitiesConnectionRetVal getConnectionDetails()
If necessary, you can override this method and return custom connection details for connecting to the database where you would like to save the plugin entities.
null, the system
database of FORMCYCLE is used.default List<String> getLiquibaseScripts()
When this plugin is installed for the first time, the scripts are run to create the initial database configuration. Then, when this plugin gets updated to a new version and you need to update the database for that plugin version, you can add additional change sets to the Liquibase script. All change sets that were run already will not be run again. For this to work, make sure you do not modify any existing change sets, as Liquibase creates a hash of the source code of each change set and issues a warning if it changed.
In some cases, your database setup may depend on the version of FORMCYCLE. If so, and you want to run certain
Liquibase scripts only for certain versions, you can check which version of FORMCYCLE is currently installed via
VersionsInfo.sdkVersion().
For more information, refer to the documentation pages of Liquibase.
ClassLoader.getResources(String).void onDatabaseReady(IPluginEntitiesParams params) throws FCPluginException
IFCPlugin.initialize(de.xima.fc.interfaces.plugin.lifecycle.IPluginInitializeData)) and after the database was set
up and is ready to be used. You may use the EntityManagerFactory that is passed to this plugin to create
new entities or fetch, update and delete existing ones. This is normally done by creating a new
EntityManager via EntityManagerFactory.createEntityManager().
However, you may find the API offered by the EntityManager hard to use. If so, you can use the DAO
(database access objects) API provided by FORMCYCLE to work with your entities more easily. First, use
IPluginEntitiesParams.getPluginEmManager() and save the em manager in a static field for later use, such as
in a bean or a filter. Later, when you need to access the database, use IPluginEmManager.newEntityContext()
to create a new entity context and pass this context to the methods offered by IAbstractDao. For example,
when you have got an entity class MyEntity and want to retrieve a list of all entities:
try (final IBaseEntityContext ec = pluginEmManager.newEntityContext()) {
// use entity context with some DAO
// this fetches all existing MyEntity
new AbstractDao(MyEntity.class) {}.all(null, new QueryCriteriaManager());
}
If you only want to retrieve a subset of entities matching a certain criterion, use the
QueryCriteriaManager API offered by FORMCYCLE.
Finally, instead of creating a new DAO on the fly, consider creating your own DAO classes by extending
IAbstractDao.
params - The parameters this method may make use of. Contains the EntityManagerFactory for working
with the entities, as well as the IPluginEmManager to make that work easier.FCPluginException - When this method performs an initial setup, such as creating new entities, and that setup
fails. If that exception is thrown, this entities plugin will be deactivated and not put into service.Copyright © 2021 XIMA MEDIA GmbH. All rights reserved.