EBX® 5.9 to EBX® 6 Migration Guide

The overall amount of memory can remain the same as for the previous version, but it must be dispatched differently between the application server and the operating system. See the Performance and tuning section for more information.

This new version offloads the indexes from memory to store them in a persistent way. Additional disk space is needed. See the Disk requirements section for more information.

Carefully read the other sections in Performance and tuning > Performance and tuning.

Consider a small table whose data could be fully contained in the cache within our custom EBX® in-memory indexes: it was then cheap to access its records repeatedly by means of random table lookups (although this is generally a discouraged access pattern for databases and information retrieval). In this new version, these accesses must be rewritten, taking advantage of the new SQL features. For example, for Java code performing a 'nested loops' join (iterating on a RequestResult from table A, and then looking up its osd:tableRef in table B): this is now better handled by using a Query using a SQL join.

EBX® now embeds the Apache Calcite framework, in particular for optimizing the submitted instances of Query and Request. However, optimizing a query has a cost in itself. Although this overhead is generally low (and well paid back) compared to that of executing the query, it might add up in some cases, particularly in the case where a loop generated numerous queries differing by only one parameter. In that case, use parameterized requests (see Request.setXPathParameter) or parameterized queries (see Query.setParameter).

Programmatic access rules concern the implementations of the Java interface AccessRule. On query execution, setting such a rule on a table implies executing the method getPermission for each record. Such an execution defeats the purpose of optimizing against an index.

Where possible, replace these programmatic access rules with the new scripted record permission rules.

Programmatic labels concern the implementations of the Java interfaces TableRefDisplay, UILabelRenderer and ConstraintEnumeration. On query execution, setting such a rule on a foreign key field implies executing the method displayOccurrence for each record. Such an execution defeats the purpose of optimizing against an index. Where possible, use a pattern string.

Programmatic filters concern the implementations of the Java interface AdaptationFilter. On query execution, using this filter implies executing the method accept for each record. Such an execution defeats the purpose of optimizing against an index. Where possible, replace programmatic filters with the new SQL queries.

Avoid constraints with unknown dependencies on large datasets, because they are checked on each validation request. See Performance and tuning for more information.

For a better performance of transactions (Java implementations of Procedure and also of TableTrigger), any unnecessary index refresh should be avoided. For more information, see Performance and tuning.

As explained in the Search limitations, inherited fields cannot benefit from the new index optimizations. Wherever possible, it is recommendable to convert these fields into linked fields.

Shut down your EBX® 5.9 application server instance.

Back up your EBX® 5.9 repository, namely the relational database objects that have names starting with the current repository prefix (ebx.persistence.table.prefix).

To facilitate the next steps, back up and delete the EBX® logs, or move them to a distinct folder.

Restart your EBX® 5.9 application server instance.

Closed dataspaces are not migrated (that is, they are deleted). If you intend to keep such dataspaces, you must re-open them prior to migrating. If you do not intend to keep them, it is a good practice to delete and purge them.

To decrease the duration of the migration, consider deleting all of the completed workflows and clean up the workflow history.

The automatic migration requires that all data models used by the repository datasets compile without errors. This strict policy has been adopted to prevent unintended loss of data, and to reach a consistent repository state at the end of the server startup.

The goal of this step is to ensure that all data models used by at least one dataset in the repository have no error.

To ensure that this is the case, first you must read the data model compilation reports:

1. The data model compilation reports are displayed in the 'kernel' log, from the server startup up to the line containing:

   ******** EBX(R) started and initialized. ********

2. In this part of the log, any data model compilation report begins with:

   ****** Schema

3. Any error message begins with:

   error [

Note: Data model compilation reports are also available through Web access, on the page Administration > Technical configuration > Modules and data models. Each report must be expanded individually.

In case a data model is in error, you must correct it. Alternatively, you can delete the datasets based on the data model in error if these datasets are no longer used (but note that you must delete the datasets in all dataspaces defining a dataset based on the data model; an alternative is to use a custom property when deploying on EBX® 6, which will globally exclude all datasets based on a schema or a list of schemas; see step 11).

After you determine that all cleanup is done, delete the log, and then return to step 3 (restart the application server), to make sure that no data models are still in error.

Note: If the DAMA add-on is used: the APIs marked as deprecated in DAMA 1.8.x are no longer available in DAMA 2.0.0. If a data model declares these deprecated APIs, then to prevent compilation errors, update the data model to use the most recent APIs.

Refer to the Digital Asset Manager documentation for the list of deprecated APIs and their replacements.

If your EBX® 5.9 environment contains deployed add-ons, an additional manual intervention is necessary. It is detailed in the next section.

Shut down your EBX® 5.9 application server instance.

Repeat backing up your EBX® 5.9 repository, as described in step 2.

Due to the conversion of some classes to interfaces in EBX® 6, all custom Java code should be recompiled against the new version. (Otherwise, the java.lang.IncompatibleClassChangeError error occurs at runtime.)

This step provides the opportunity to assess some of the backward compatibility issues documented in the release note and those coming from the add-ons.

Replace all ebx*.war and ebx.jar files deployed on your application server with the new artefacts provided with EBX® 6. See Jakarta EE deployment for more information.

If you use EBX® add-ons, then replace all ebx-addon-*.war files and ebx-addons.jar files with those provided with the new bundle complying with EBX® 6.

Restart the application server instance, now deployed with EBX® 6.

In the case where at least a data model is still in error, the automatic migration is automatically stopped and a log details which datasets are concerned by these errors. To ease the corrections, the logs also provide a suggestion feeding the property ebx.migration.5to6.excludeAllDatasetsOnDataModels with the locations of the failing schemas, in the expected format. You then have two options:

• If you accept these datasets to be excluded from the migration, copy this property to ebx.properties.

• If you do not accept this suggestion, you must return to step 3.

If no data model is in error, then the database schema and data are automatically migrated. This process might take time, depending on the volume of data.