Package de.xima.fc.plugin.entities

Interface IPluginEntities

All Superinterfaces:
IFCPlugin, INamedUiElement, INameProviding, ITransferable, Serializable
public interface IPluginEntities extends IFCPlugin
Interface for an entities plugin. This type of plugin lets you add custom JPA (Java persistence API) 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:

  • one or multiple entity classes that must have the Entity annotation
  • a Liquibase script that creates the required database tables and can be used for updates, and
  • a DataSource with the connection details to a database (defaults to the formcycle database)
The entity classes are picked up automatically as long as they are annotated with the 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.

Author:
XIMA MEDIA GmbH

  • Method Details

    • getConnectionDetails

      default IPluginEntitiesConnectionRetVal getConnectionDetails()
      By default, plugin entities are saved in the system database, ie the same database that formcycle uses. In this case, make sure the table names for the plugin entities do not collide with any pre-existing formcycle table names. We recommend you add a custom prefix to each table name.

      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.

      Returns:
      The connection details to the database that will store the plugin entities. If null, the system database of formcycle is used.

    • getLiquibaseScripts

      default List<String> getLiquibaseScripts()
      This method may be used to return a list of Liquibase scripts for initializing or updating the database. The Liquibase scripts are run in the order as returned by this method. A Liquibase scripts consists of a list of change sets. Each change set is responsible for a single logical database modification, such as creating a table or adding some new columns to a table. If an empty list is returned, no Liquibase script are run.

      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.

      Returns:
      A list of Liquibase scripts for initializing or updating the database. May be an empty list in case you need to set up the database. Each item must be a path to a Liquibase XML file, in the format accepted by ClassLoader.getResources(String).

    • onDatabaseReady

      void onDatabaseReady(IPluginEntitiesParams params) throws FCPluginException
      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. 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, Long, IBaseEntityContext>(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.

      Parameters:
      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.
      Throws:
      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.