Package su.onno.ui.migration

Class Ui2MigrationTool

java.lang.Object
su.onno.ui.migration.Ui2MigrationTool
public final class Ui2MigrationTool extends Object
One-time conversion support for applications moving legacy UI values and authored metadata to the 2.0 contracts.

Create this inside an AppMigration from its MigrationContext. Column helpers scan non-null values and apply changed rows in prepared batches inside the migration's existing transaction. Identifiers are strictly validated before being interpolated into SQL. A malformed or ambiguous legacy value aborts the migration with its table/column/row id in the error rather than leaving a partially guessed conversion.


 public void migrate(MigrationContext context) throws Exception {
     var tool = new Ui2MigrationTool(context, mediaStorage);
     tool.migrateEnumNames("catalog_orders", "_id", "status", OrderStatus.class);
     tool.migrateDataUrlImages("catalog_people", "_id", "avatar_url");
     tool.migrateGeoPoints("catalog_sites", "_id", "location");
 }

The source-only helpers are deliberately explicit. In particular, a bare "currency" has no safe universal replacement, so callers must supply their ISO 4217 currency. They can use these helpers from a small source/config codemod or to verify replacements before upgrading.

  • Constructor Details

    • Ui2MigrationTool

      public Ui2MigrationTool(MigrationContext context, MediaStorage mediaStorage)
      A tool with media migration enabled. The supplied storage is the application's configured MediaStorage, so converted data URLs land in the same backend as new uploads.

    • Ui2MigrationTool

      public Ui2MigrationTool(MigrationContext context)
      A tool for enum/geo/source-metadata migrations only. Calling an image conversion fails fast with an explanation that a MediaStorage must be supplied.

    • Ui2MigrationTool

      public Ui2MigrationTool(MigrationContext context, MediaStorage mediaStorage, int batchSize)
      Constructor with an explicit update batch size, primarily for large application tables.

  • Method Details

    • migrateEnumNames

      public <E extends Enum<E>> Ui2MigrationTool.MigrationResult migrateEnumNames(String table, String idColumn, String valueColumn, Class<E> enumType) throws Exception
      Replace legacy Java enum constant names with their deterministic stored UUIDs. Already-canonical UUID values are left unchanged; unknown names abort the migration.
      Throws:
      Exception

    • migrateDataUrlImages

      public Ui2MigrationTool.MigrationResult migrateDataUrlImages(String table, String idColumn, String valueColumn) throws Exception
      Decode every legacy base64 data:image/... URL in an image/gallery column, store it through MediaStorage, and replace it with the returned URL. Newline-joined galleries are converted item by item; already-stored URLs are unchanged.
      Throws:
      Exception

    • migrateGeoPoints

      public Ui2MigrationTool.MigrationResult migrateGeoPoints(String table, String idColumn, String valueColumn) throws Exception
      Replace a legacy "lat,lng" point string with a GeoJSON FeatureCollection in the same column. Existing JSON is unchanged. Afterward, change authored metadata from widget("map") / map().field(...) to widget("geojson") / map().geoJson(...).
      Throws:
      Exception

    • canonicalEnumId

      public static <E extends Enum<E>> UUID canonicalEnumId(Class<E> enumType, String constantName)
      Convert one legacy enum constant name to its deterministic UUID.

    • canonicalMediaValue

      public String canonicalMediaValue(String value) throws IOException
      Store one legacy data-URL value (or every item of a newline-joined gallery) and return canonical stored-media URL(s). Values that contain no data URL pass through unchanged.
      Throws:
      IOException

    • canonicalGeoJson

      public static String canonicalGeoJson(String value)
      Convert a legacy point string to canonical GeoJSON. An existing object with a recognized GeoJSON type passes through unchanged; malformed JSON/coordinates and out-of-range points fail fast.

    • canonicalCurrencyFormat

      public static String canonicalCurrencyFormat(String format, String defaultCurrency)
      Make a field-format hint explicit. A bare currency is rewritten with the caller's ISO 4217 code; an existing currency:xxx is validated and normalized to uppercase.

    • canonicalIcon

      public static String canonicalIcon(String icon)
      Return the current Lucide name for a formerly accepted alias; current names pass through.

    • canonicalWidget

      public static String canonicalWidget(String widget)
      Rewrite a legacy point-widget name to the canonical GeoJSON editor name.

    • canonicalMapConfigKey

      public static String canonicalMapConfigKey(String key)
      Rewrite the old dashboard/list map config key to the canonical GeoJSON key.