@itwin/core-backend 5.6.0-dev.6 → 5.6.0-dev.8

package/lib/esm/IModelDb.js

@@ -81,6 +81,24 @@ class IModelSettings extends SettingsImpl {
         yield* IModelHost.appWorkspace.settings.getSettingEntries(name);
     }
 }
+/**
+ * Strategy for transforming data during schema import.
+ * @beta
+ */
+export var DataTransformationStrategy;
+(function (DataTransformationStrategy) {
+    /** No data transformation will be performed after schema import. */
+    DataTransformationStrategy["None"] = "None";
+    /** Data transformation will be performed using a temporary snapshot created before schema import.
+     *  Useful for complex transformations requiring full read access to complete pre-import state for lazy conversion.
+     *  Note: Creates a complete copy of the briefcase file, which may be large.
+     */
+    DataTransformationStrategy["Snapshot"] = "Snapshot";
+    /** Data transformation will be performed using in-memory cached data created before schema import.
+     *  Useful for lightweight transformations involving limited data.
+     */
+    DataTransformationStrategy["InMemory"] = "InMemory";
+})(DataTransformationStrategy || (DataTransformationStrategy = {}));
 /** An iModel database file. The database file can either be a briefcase or a snapshot.
  * @see [Accessing iModels]($docs/learning/backend/AccessingIModels.md)
  * @see [About IModelDb]($docs/learning/backend/IModelDb.md)
@@ -715,21 +733,68 @@ export class IModelDb extends IModel {
             this.clearCaches();
         }
     }
-    /** Import an ECSchema. On success, the schema definition is stored in the iModel.
-     * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
-     * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
-     * @param schemaFileName  array of Full paths to ECSchema.xml files to be imported.
-     * @param {SchemaImportOptions} options - options during schema import.
-     * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
-     * @note Changes are saved if importSchemas is successful and abandoned if not successful.
-     * - You can use NativeLoggerCategory to turn on the native logs. You can also control [what exactly is logged by the loggers](https://www.itwinjs.org/learning/common/logging/#controlling-what-is-logged).
-     * - See [Schema Versioning]($docs/bis/guide/schema-evolution/schema-versioning-and-generations.md) for more information on acceptable changes to schemas.
-     * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
-    * @see querySchemaVersion
+    /** Helper to clean up snapshot resources safely
+     * @internal
      */
-    async importSchemas(schemaFileNames, options) {
-        if (schemaFileNames.length === 0)
-            return;
+    cleanupSnapshot(resources) {
+        if (resources.snapshot) {
+            const pathName = resources.snapshot.pathName;
+            resources.snapshot.close();
+            if (pathName && IModelJsFs.existsSync(pathName)) {
+                IModelJsFs.removeSync(pathName);
+            }
+        }
+    }
+    async preSchemaImportCallback(callback, context) {
+        const callbackResources = {
+            transformStrategy: DataTransformationStrategy.None,
+        };
+        try {
+            if (callback?.preSchemaImportCallback) {
+                const callbackResult = await callback.preSchemaImportCallback(context);
+                callbackResources.transformStrategy = callbackResult.transformStrategy;
+                if (callbackResult.transformStrategy === DataTransformationStrategy.Snapshot) {
+                    // Create temporary snapshot file
+                    const snapshotDb = SnapshotDb.createFrom(this, `${this.pathName}.snapshot-${Date.now()}`);
+                    callbackResources.snapshot = snapshotDb;
+                }
+                else if (callbackResult.transformStrategy === DataTransformationStrategy.InMemory) {
+                    if (callbackResult.cachedData === undefined) {
+                        throw new IModelError(IModelStatus.BadRequest, "InMemory transform strategy requires cachedData to be provided.");
+                    }
+                    callbackResources.cachedData = callbackResult.cachedData;
+                }
+            }
+        }
+        catch (callbackError) {
+            this.abandonChanges();
+            this.cleanupSnapshot(callbackResources);
+            throw new IModelError(callbackError.errorNumber ?? IModelStatus.BadRequest, `Failed to execute preSchemaImportCallback: ${callbackError.message}`);
+        }
+        return callbackResources;
+    }
+    async postSchemaImportCallback(callback, context) {
+        if (context.resources.transformStrategy === DataTransformationStrategy.Snapshot && (context.resources.snapshot === undefined || !IModelJsFs.existsSync(context.resources.snapshot.pathName))) {
+            throw new IModelError(IModelStatus.BadRequest, "Snapshot transform strategy requires a snapshot to be created");
+        }
+        if (context.resources.transformStrategy === DataTransformationStrategy.InMemory && context.resources.cachedData === undefined) {
+            throw new IModelError(IModelStatus.BadRequest, "InMemory transform strategy requires cachedData to be provided.");
+        }
+        try {
+            if (callback?.postSchemaImportCallback)
+                await callback.postSchemaImportCallback(context);
+        }
+        catch (callbackError) {
+            this.abandonChanges();
+            throw new IModelError(callbackError.errorNumber ?? IModelStatus.BadRequest, `Failed to execute postSchemaImportCallback: ${callbackError.message}`);
+        }
+        finally {
+            // Always clean up snapshot, whether success or error
+            this.cleanupSnapshot(context.resources);
+        }
+    }
+    /** Shared implementation for importing schemas from file or string. */
+    async importSchemasInternal(schemas, options, nativeImportOp) {
         if (this instanceof BriefcaseDb) {
             if (this.txns.rebaser.isRebasing) {
                 throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while rebasing");
@@ -738,13 +803,25 @@ export class IModelDb extends IModel {
                 throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
             }
         }
+        if (options?.channelUpgrade) {
+            try {
+                await this.channels.upgradeChannel(options.channelUpgrade, this, options.data);
+            }
+            catch (error) {
+                this.abandonChanges();
+                throw error;
+            }
+        }
+        let preSchemaImportCallbackResult = { transformStrategy: DataTransformationStrategy.None };
+        if (options?.schemaImportCallbacks?.preSchemaImportCallback)
+            preSchemaImportCallbackResult = await this.preSchemaImportCallback(options.schemaImportCallbacks, { iModel: this, data: options.data, schemaData: schemas });
         const maybeCustomNativeContext = options?.ecSchemaXmlContext?.nativeContext;
         if (this[_nativeDb].schemaSyncEnabled()) {
             await SchemaSync.withLockedAccess(this, { openMode: OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
                 const schemaSyncDbUri = syncAccess.getUri();
                 this.saveChanges();
                 try {
-                    this[_nativeDb].importSchemas(schemaFileNames, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
+                    nativeImportOp(schemas, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
                 }
                 catch (outerErr) {
                     if (DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
@@ -752,7 +829,7 @@ export class IModelDb extends IModel {
                         if (this[_nativeDb].getITwinId() !== Guid.empty)
                             await this.acquireSchemaLock();
                         try {
-                            this[_nativeDb].importSchemas(schemaFileNames, { schemaLockHeld: true, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
+                            nativeImportOp(schemas, { schemaLockHeld: true, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
                         }
                         catch (innerErr) {
                             throw new IModelError(innerErr.errorNumber, innerErr.message);
@@ -772,71 +849,48 @@ export class IModelDb extends IModel {
             if (this[_nativeDb].getITwinId() !== Guid.empty) // if this iModel is associated with an iTwin, importing schema requires the schema lock
                 await this.acquireSchemaLock();
             try {
-                this[_nativeDb].importSchemas(schemaFileNames, nativeImportOptions);
+                nativeImportOp(schemas, nativeImportOptions);
             }
             catch (err) {
                 throw new IModelError(err.errorNumber, err.message);
             }
         }
         this.clearCaches();
+        if (options?.schemaImportCallbacks?.postSchemaImportCallback)
+            await this.postSchemaImportCallback(options.schemaImportCallbacks, { iModel: this, resources: preSchemaImportCallbackResult, data: options.data });
+    }
+    /** Import an ECSchema. On success, the schema definition is stored in the iModel.
+     * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
+     * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
+     * @param schemaFileName  array of Full paths to ECSchema.xml files to be imported.
+     * @param {SchemaImportOptions} options - options during schema import.
+     * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
+     * @note Changes are saved if importSchemas is successful and abandoned if not successful.
+     * - You can use NativeLoggerCategory to turn on the native logs. You can also control [what exactly is logged by the loggers](https://www.itwinjs.org/learning/common/logging/#controlling-what-is-logged).
+     * - See [Schema Versioning]($docs/bis/guide/schema-evolution/schema-versioning-and-generations.md) for more information on acceptable changes to schemas.
+     * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
+     * @see querySchemaVersion
+     */
+    async importSchemas(schemaFileNames, options) {
+        if (schemaFileNames.length === 0)
+            return;
+        await this.importSchemasInternal(schemaFileNames, options, (schemas, importOptions) => this[_nativeDb].importSchemas(schemas, importOptions));
     }
     /** Import ECSchema(s) serialized to XML. On success, the schema definition is stored in the iModel.
      * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
      * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
      * @param serializedXmlSchemas  The xml string(s) created from a serialized ECSchema.
+     * @param {SchemaImportOptions} options - options during schema import.
      * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
      * @note Changes are saved if importSchemaStrings is successful and abandoned if not successful.
      * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
      * @see querySchemaVersion
      * @alpha
      */
-    async importSchemaStrings(serializedXmlSchemas) {
+    async importSchemaStrings(serializedXmlSchemas, options) {
         if (serializedXmlSchemas.length === 0)
             return;
-        if (this instanceof BriefcaseDb) {
-            if (this.txns.rebaser.isRebasing) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while rebasing");
-            }
-            if (this.txns.isIndirectChanges) {
-                throw new IModelError(IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
-            }
-        }
-        if (this[_nativeDb].schemaSyncEnabled()) {
-            await SchemaSync.withLockedAccess(this, { openMode: OpenMode.Readonly, operationName: "schemaSync" }, async (syncAccess) => {
-                const schemaSyncDbUri = syncAccess.getUri();
-                this.saveChanges();
-                try {
-                    this[_nativeDb].importXmlSchemas(serializedXmlSchemas, { schemaLockHeld: false, schemaSyncDbUri });
-                }
-                catch (outerErr) {
-                    if (DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
-                        this.abandonChanges();
-                        if (this[_nativeDb].getITwinId() !== Guid.empty)
-                            await this.acquireSchemaLock();
-                        try {
-                            this[_nativeDb].importXmlSchemas(serializedXmlSchemas, { schemaLockHeld: true, schemaSyncDbUri });
-                        }
-                        catch (innerErr) {
-                            throw new IModelError(innerErr.errorNumber, innerErr.message);
-                        }
-                    }
-                    else {
-                        throw new IModelError(outerErr.errorNumber, outerErr.message);
-                    }
-                }
-            });
-        }
-        else {
-            if (this.iTwinId && this.iTwinId !== Guid.empty) // if this iModel is associated with an iTwin, importing schema requires the schema lock
-                await this.acquireSchemaLock();
-            try {
-                this[_nativeDb].importXmlSchemas(serializedXmlSchemas, { schemaLockHeld: true });
-            }
-            catch (err) {
-                throw new IModelError(err.errorNumber, err.message);
-            }
-        }
-        this.clearCaches();
+        await this.importSchemasInternal(serializedXmlSchemas, options, (schemas, importOptions) => this[_nativeDb].importXmlSchemas(schemas, importOptions));
     }
     /** Find an opened instance of any subclass of IModelDb, by filename
      * @note this method returns an IModelDb if the filename is open for *any* subclass of IModelDb