add new wot-models definition update endpoint #1843

[hu-ahmed]

#1843

The migrateThingDefinition endpoint introduces a comprehensive mechanism for migrating a Thing's definition while ensuring data consistency and applying necessary migrations. This endpoint is designed to facilitate seamless updates by incorporating a structured approach to definition changes and migration payloads.

Key Features:

• Definition Update with Skeleton Generation:
  The provided Thing definition URL is used to generate a new skeleton Thing, which serves as the baseline for the update.
  The skeleton includes a hierarchical representation of the Thing, ensuring consistency with the WoT model.

• Patch Condition Evaluation:
  The migration payload can include multiple patch conditions, evaluated using RQL-based expressions to determine whether specific updates should be applied.
  This allows for conditional updates based on existing Thing attributes or feature values.

• Merging Strategy:
  The update process merges the newly generated skeleton with the existing Thing while preserving essential attributes and properties.
  An optional initialization step applies default values from the skeleton to fill in missing or incomplete properties.

• Migration Payload Application:
  The provided migration payload is selectively merged into the updated Thing, allowing for targeted modifications without overriding all properties.
  Ensures data integrity by applying only necessary changes based on predefined rules.

• Validation and Persistence:
  Before finalizing the update, the modified Thing undergoes WoT model validation based on the current configuration, so either it will be rejected or logged as warning in case of inconsistency.

• API Usage:
  Endpoint:
  POST /api/2/things/{thingId}/migrateDefinition
  Request Body:

{
  "thingDefinitionUrl": "https://models.example.com/thing-definition-1.0.0.tm.jsonld",
  "migrationPayload": {
    "attributes": {
      "manufacturer": "New Corp",
      "location": "Berlin, main floor"
    },
    "features": {
      "thermostat": {
        "properties": {
          "status": {
            "temperature": {
              "value": 23.5,
              "unit": "DEGREE_CELSIUS"
            }
          }
        }
      }
    }
  },
  "patchConditions": {
    "thing:/features/thermostat": "not(exists(/features/thermostat))"
  },
  "initializeMissingPropertiesFromDefaults": true
}

[thjaeckle]

Hi @hu-ahmed and thanks a lot for providing this PR.

Looks already really promising .. I did a quick check and left a few comments before going deeper :)

[thjaeckle]

orElseThrow is not good here .. it will throw an IllegalArgumentException which will not contain any useful information about why this failed.
I would suggest to throw a more meaningful subclass of WotException, also maintaining dittoHeaders to have proper propagation of correlation-id, trace, etc.

[thjaeckle]

Unit test is missing for this strategy class.

[thjaeckle]

this parameter patchConditions is not marked as @Nullable and (I think) cannot be null from the code flow.
So no need to check for null ..

[thjaeckle]

Why apply the mergeStrategy for the existingThing here?
I would expect the updatedThing.

So currently this e.g. validates the old, existingThing (as part of the MergeThingStrategy) against the WoT model instead of the new one.