RichText Data Migration - fieldenms/tg GitHub Wiki

This document is a guide to using the RichText data migration tool.

The tool's purpose is to automate some parts of the data migration process specifically for RichText data.

Scenarios in which the tool is applicable:

• An entity property changes type from String to RichText.
• An entity property typed with String is replaced by a property typed with RichText.

Given a description of data migration, the tool generates SQL that performs the migration.

The tool is designed for the blue/green deployment strategy, and generates SQL scripts that suppport each deployment stage.

The tool is represented by Java class ua.com.fielden.platform.data.StringToRichTextMigration located in the platform-db-evolution module. The documentation of this class contains further details about its operation.

The intended usage of the tool is similar to that of the established GenDdl tool: an application-specific class should be created with method main that instantiates the tool via an injector.

[!IMPORTANT] Make sure that the application's Maven module used to launch the tool depends on platform-db-evolution, since this is where the tool itself is located.

The following example shows how to replace property WorkActivity.desc : String with WorkActivity.note : RichText.

package fielden.dev_mod.util;

import fielden.work.WorkActivity;
import org.apache.logging.log4j.Logger;
import ua.com.fielden.platform.data.StringToRichTextMigration;

import java.io.FileInputStream;
import java.util.Properties;

import static org.apache.logging.log4j.LogManager.getLogger;

public class RichTextMigration {

    private static final Logger LOGGER = getLogger();

    public static void main(String[] args)
            throws Exception
    {
        LOGGER.info("Initialising ...");
        final String configFileName = args.length == 1 ? args[0] : "src/main/resources/application.properties";
        final Properties props = new Properties();
        try (final FileInputStream in = new FileInputStream(configFileName)) {
            props.load(in);
        }

        final var config = new DataPopulationConfig(props);
  
        LOGGER.info("Running the RichText data migration tool.");
        final var tool = config.getInstance(StringToRichTextMigration.class);
        final var sql = tool.migrateToNewProperty(WorkActivity.class, "desc", "note")
                            .generateSql();
        System.out.println(sql);
    }

}

To futher understand the tool's operation and the kinds of input it accepts, please refer to its JavaDoc.

Migration of desc

Given the special role of property desc, it cannot be modelled with RichText directly (its type can only be String). There are plans to remove desc from AbstractEntity and lift the restriction on its type. Meanwhile, the following approach should be followed to migrate desc to RichText.

1. Introduce new persistent property richDesc : RichText.
2. Generate SQL migration scripts, as usual, using StringToRichTextMigration.
3. Make desc calculated. The expression should be richDesc.coreText.
4. Adjust usages of desc where necessary. Primarily, in Web UI configurations, by replacing it with richDesc.

Fetch models

Property desc is fetched implicitly, even when it is calculated, so it is not necessary to fetch it explicitly. For more details see Issue 2381.

Needless to say, richDesc should be fetched explicitly where necessary.