@itwin/core-backend 4.1.0-dev.8 → 4.1.0-dev.80

package/lib/cjs/IModelDb.js

@@ -9,13 +9,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StandaloneDb = exports.SnapshotDb = exports.BriefcaseDb = exports.IModelDb = exports.BriefcaseLocalValue = void 0;
 const path_1 = require("path");
+const fs = require("fs");
 const core_bentley_1 = require("@itwin/core-bentley");
 const core_common_1 = require("@itwin/core-common");
 const core_geometry_1 = require("@itwin/core-geometry");
 const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
 const BriefcaseManager_1 = require("./BriefcaseManager");
+const ChannelControl_1 = require("./ChannelControl");
 const CheckpointManager_1 = require("./CheckpointManager");
 const ClassRegistry_1 = require("./ClassRegistry");
+const CloudSqlite_1 = require("./CloudSqlite");
 const CodeService_1 = require("./CodeService");
 const CodeSpecs_1 = require("./CodeSpecs");
 const ConcurrentQuery_1 = require("./ConcurrentQuery");
@@ -23,6 +26,7 @@ const ECSqlStatement_1 = require("./ECSqlStatement");
 const Element_1 = require("./Element");
 const ElementAspect_1 = require("./ElementAspect");
 const ElementGraphics_1 = require("./ElementGraphics");
+const Entity_1 = require("./Entity");
 const GeoCoordConfig_1 = require("./GeoCoordConfig");
 const IModelHost_1 = require("./IModelHost");
 const IModelJsFs_1 = require("./IModelJsFs");
@@ -33,9 +37,9 @@ const ServerBasedLocks_1 = require("./ServerBasedLocks");
 const SqliteStatement_1 = require("./SqliteStatement");
 const TxnManager_1 = require("./TxnManager");
 const ViewDefinition_1 = require("./ViewDefinition");
+const ViewStore_1 = require("./ViewStore");
 const Settings_1 = require("./workspace/Settings");
 const Workspace_1 = require("./workspace/Workspace");
-const ChannelControl_1 = require("./ChannelControl");
 // spell:ignore fontid fontmap
 const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.IModelDb;
 /** A null-implementation of LockControl that does not attempt to limit access between briefcases. This relies on change-merging to resolve conflicts. */
@@ -247,9 +251,7 @@ class IModelDb extends core_common_1.IModel {
      * @internal
      */
     get isStandalone() { return false; }
-    /** Type guard for instanceof [[StandaloneDb]]
-     * @internal
-     */
+    /** Type guard for instanceof [[StandaloneDb]]. */
     isStandaloneDb() { return this.isStandalone; }
     /** Return `true` if the underlying nativeDb is open and valid.
      * @internal
@@ -318,6 +320,12 @@ class IModelDb extends core_common_1.IModel {
         }
     }
     /** Allow to execute query and read results along with meta data. The result are streamed.
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     * - [ECSQL Row Format]($docs/learning/ECSQLRowFormat)
+     *
      * @param params The values to bind to the parameters (if the ECSQL has any).
      * @param config Allow to specify certain flags which control how query is executed.
      * @returns Returns an [ECSqlReader]($common) which helps iterate over the result set and also give access to metadata.
@@ -744,7 +752,7 @@ class IModelDb extends core_common_1.IModel {
         }
         return schemaState;
     }
-    /** Get the ClassMetaDataRegistry for this iModel.
+    /** The registry of entity metadata for this iModel.
      * @internal
      */
     get classMetaDataRegistry() {
@@ -784,7 +792,7 @@ class IModelDb extends core_common_1.IModel {
      */
     constructEntity(props) {
         const jsClass = this.getJsClass(props.classFullName);
-        return new jsClass(props, this);
+        return Entity_1.Entity.instantiate(jsClass, props, this);
     }
     /** Get the JavaScript class that handles a given entity class.  */
     getJsClass(classFullName) {
@@ -1023,7 +1031,7 @@ class IModelDb extends core_common_1.IModel {
     }
     /** Request geometry stream information from an element in binary format instead of json.
      * @returns IModelStatus.Success if successful
-     * @alpha
+     * @beta
      */
     elementGeometryRequest(requestProps) {
         return this.nativeDb.processGeometryStream(requestProps);
@@ -1053,9 +1061,7 @@ class IModelDb extends core_common_1.IModel {
             stmt.bindString(1, IModelDb._settingPropNamespace);
             stmt.bindString(2, name);
             stmt.bindString(3, JSON.stringify(dict));
-            const rc = stmt.step();
-            if (rc !== core_bentley_1.DbResult.BE_SQLITE_DONE)
-                throw new core_common_1.IModelError(rc, "cannot save setting");
+            stmt.stepForWrite();
         });
         this.saveChanges("add settings");
     }
@@ -1067,9 +1073,7 @@ class IModelDb extends core_common_1.IModel {
         this.withSqliteStatement("DELETE FROM be_Prop WHERE Namespace=? AND Name=?", (stmt) => {
             stmt.bindString(1, IModelDb._settingPropNamespace);
             stmt.bindString(2, name);
-            const rc = stmt.step();
-            if (rc !== core_bentley_1.DbResult.BE_SQLITE_DONE)
-                throw new core_common_1.IModelError(rc, "cannot delete setting");
+            stmt.stepForWrite();
         });
         this.saveChanges("delete settings");
     }
@@ -1079,7 +1083,7 @@ class IModelDb extends core_common_1.IModel {
             return;
         this.withSqliteStatement("SELECT Name,StrData FROM be_Prop WHERE Namespace=?", (stmt) => {
             stmt.bindString(1, IModelDb._settingPropNamespace);
-            while (stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW) {
+            while (stmt.nextRow()) {
                 try {
                     const dict = JSON.parse(stmt.getValueString(1));
                     this.workspace.settings.addDictionary(stmt.getValueString(0), Settings_1.SettingsPriority.iModel, dict);
@@ -1125,8 +1129,9 @@ exports.IModelDb = IModelDb;
         tryGetModelProps(id) {
             return this.tryGetModelJson({ id });
         }
-        /** Query for the last modified time of the specified Model.
-         * @internal
+        /** Query for the last modified time for a [[Model]].
+         * @param modelId The Id of the model.
+         * @throws IModelError if `modelId` does not identify a model in the iModel.
          */
         queryLastModifiedTime(modelId) {
             const sql = `SELECT LastMod FROM ${Model_1.Model.classFullName} WHERE ECInstanceId=:modelId`;
@@ -1313,6 +1318,18 @@ exports.IModelDb = IModelDb;
         constructor(_iModel) {
             this._iModel = _iModel;
         }
+        getFederationGuidFromId(id) {
+            return this._iModel.withPreparedSqliteStatement(`SELECT FederationGuid FROM bis_Element WHERE Id=?`, (stmt) => {
+                stmt.bindId(1, id);
+                return stmt.nextRow() ? stmt.getValueGuid(0) : undefined;
+            });
+        }
+        getIdFromFederationGuid(guid) {
+            return guid ? this._iModel.withPreparedSqliteStatement(`SELECT Id FROM bis_Element WHERE FederationGuid=?`, (stmt) => {
+                stmt.bindGuid(1, guid);
+                return !stmt.nextRow() ? undefined : stmt.getValueId(0);
+            }) : undefined;
+        }
         /** Read element data from the iModel as JSON
          * @param elementIdArg a json string with the identity of the element to load. Must have one of "id", "federationGuid", or "code".
          * @returns The JSON properties of the element.
@@ -1433,8 +1450,9 @@ exports.IModelDb = IModelDb;
                 return stmt.getValue(0).getId();
             });
         }
-        /** Query for the last modified time of the specified element.
-         * @internal
+        /** Query for an [[Element]]'s last modified time.
+         * @param elementId The Id of the element.
+         * @throws IModelError if `elementId` does not identify an element in the iModel.
          */
         queryLastModifiedTime(elementId) {
             const sql = "SELECT LastMod FROM BisCore:Element WHERE ECInstanceId=:elementId";
@@ -1740,6 +1758,37 @@ exports.IModelDb = IModelDb;
         constructor(_iModel) {
             this._iModel = _iModel;
         }
+        get hasViewStore() { return undefined !== this._viewStore; }
+        /** @beta */
+        get viewStore() {
+            if (undefined === this._viewStore)
+                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "No ViewStore available");
+            return this._viewStore;
+        }
+        set viewStore(viewStore) {
+            this._viewStore = viewStore;
+        }
+        /** @beta */
+        async accessViewStore(args) {
+            let props = args.props;
+            if (undefined === props) {
+                const propsString = this._iModel.queryFilePropertyString(Views.viewStoreProperty);
+                if (!propsString)
+                    throw new Error("iModel does not have a default ViewStore");
+                props = JSON.parse(propsString);
+            }
+            const accessToken = await CloudSqlite_1.CloudSqlite.requestToken(props);
+            if (!this._viewStore)
+                this._viewStore = new ViewStore_1.ViewStore.CloudAccess({ ...props, accessToken, iModel: this._iModel });
+            this._viewStore.container.accessToken = accessToken;
+            return this._viewStore;
+        }
+        /** @beta */
+        saveDefaultViewStore(arg) {
+            const props = { baseUri: arg.baseUri, containerId: arg.containerId, storageType: arg.storageType }; // sanitize to only known properties
+            this._iModel.saveFileProperty(Views.viewStoreProperty, JSON.stringify(props));
+            this._iModel.saveChanges("update default ViewStore");
+        }
         /** Query for the array of ViewDefinitionProps of the specified class and matching the specified IsPrivate setting.
          * @param className Query for view definitions of this class.
          * @param wantPrivate If true, include private view definitions.
@@ -1761,11 +1810,6 @@ exports.IModelDb = IModelDb;
          * @param params Specifies the query by which views are selected.
          * @param callback Function invoked for each ViewDefinition matching the query. Return false to terminate iteration, true to continue.
          * @returns true if all views were iterated, false if iteration was terminated early due to callback returning false.
-         *
-         * **Example: Finding all views of a specific DrawingModel**
-         * ``` ts
-         * [[include:IModelDb.Views.iterateViews]]
-         * ```
          */
         iterateViews(params, callback) {
             const ids = this._iModel.queryEntityIds(params);
@@ -1783,75 +1827,81 @@ exports.IModelDb = IModelDb;
             }
             return finished;
         }
-        loadViewStateProps(viewDefinitionElement, options, drawingExtents) {
-            const elements = this._iModel.elements;
-            const viewDefinitionProps = viewDefinitionElement.toJSON();
-            const categorySelectorProps = elements.getElementProps(viewDefinitionProps.categorySelectorId);
-            const displayStyleProps = elements.getElementProps({
-                id: viewDefinitionProps.displayStyleId,
-                displayStyle: options?.displayStyle,
-            });
-            const viewStateData = {
-                viewDefinitionProps,
-                displayStyleProps,
-                categorySelectorProps,
-            };
-            const modelSelectorId = viewDefinitionProps.modelSelectorId;
-            if (modelSelectorId !== undefined) {
-                viewStateData.modelSelectorProps = elements.getElementProps(modelSelectorId);
-            }
-            else if (viewDefinitionElement instanceof ViewDefinition_1.SheetViewDefinition) {
-                viewStateData.sheetProps = elements.getElementProps(viewDefinitionElement.baseModelId);
-                viewStateData.sheetAttachments = Array.from(this._iModel.queryEntityIds({
+        loadViewData(viewId, options) {
+            const iModel = this._iModel;
+            const elements = iModel.elements;
+            const loader = (() => {
+                if (core_common_1.ViewStoreRpc.isViewStoreId(viewId)) {
+                    const reader = this.viewStore.reader;
+                    return {
+                        loadView: () => reader.getViewDefinitionSync({ viewId }),
+                        loadCategorySelector: (id) => reader.getCategorySelectorSync({ id, bindings: options?.queryBindings?.categorySelector }),
+                        loadDisplayStyle: (id) => reader.getDisplayStyleSync({ id, opts: options?.displayStyle }),
+                        loadModelSelector: (id) => reader.getModelSelectorSync({ id, bindings: options?.queryBindings?.modelSelector }),
+                    };
+                }
+                return {
+                    loadView: () => elements.getElementProps(viewId),
+                    loadCategorySelector: (id) => elements.getElementProps(id),
+                    loadDisplayStyle: (id) => elements.getElementProps({ id, displayStyle: options?.displayStyle }),
+                    loadModelSelector: (id) => elements.getElementProps(id),
+                };
+            })();
+            const props = {};
+            props.viewDefinitionProps = loader.loadView();
+            props.categorySelectorProps = loader.loadCategorySelector(props.viewDefinitionProps.categorySelectorId);
+            props.displayStyleProps = loader.loadDisplayStyle(props.viewDefinitionProps.displayStyleId);
+            const modelSelectorId = props.viewDefinitionProps.modelSelectorId;
+            if (modelSelectorId !== undefined)
+                props.modelSelectorProps = loader.loadModelSelector(modelSelectorId);
+            const viewClass = iModel.getJsClass(props.viewDefinitionProps.classFullName);
+            const baseModelId = props.viewDefinitionProps.baseModelId;
+            if (viewClass.is(ViewDefinition_1.SheetViewDefinition)) {
+                props.sheetProps = elements.getElementProps(baseModelId);
+                props.sheetAttachments = Array.from(iModel.queryEntityIds({
                     from: "BisCore.ViewAttachment",
-                    where: `Model.Id=${viewDefinitionElement.baseModelId}`,
+                    where: `Model.Id=${baseModelId}`,
                 }));
             }
-            else if (viewDefinitionElement instanceof ViewDefinition_1.DrawingViewDefinition) {
-                // Ensure view has known extents
-                if (drawingExtents && !drawingExtents.isNull)
-                    viewStateData.modelExtents = drawingExtents.toJSON();
+            else if (viewClass.is(ViewDefinition_1.DrawingViewDefinition)) {
                 // Include information about the associated [[SectionDrawing]], if any.
                 // NB: The SectionDrawing ECClass may not exist in the iModel's version of the BisCore ECSchema.
-                try {
-                    const sectionDrawing = this._iModel.elements.tryGetElement(viewDefinitionElement.baseModelId);
-                    if (sectionDrawing && sectionDrawing.spatialView && core_bentley_1.Id64.isValidId64(sectionDrawing.spatialView.id)) {
-                        viewStateData.sectionDrawing = {
-                            spatialView: sectionDrawing.spatialView.id,
-                            displaySpatialView: true === sectionDrawing.jsonProperties.displaySpatialView,
-                            drawingToSpatialTransform: sectionDrawing.jsonProperties.drawingToSpatialTransform,
-                        };
-                    }
-                }
-                catch {
-                    //
+                const sectionDrawing = iModel.elements.tryGetElement(baseModelId);
+                if (sectionDrawing && sectionDrawing.spatialView && core_bentley_1.Id64.isValidId64(sectionDrawing.spatialView.id)) {
+                    props.sectionDrawing = {
+                        spatialView: sectionDrawing.spatialView.id,
+                        displaySpatialView: true === sectionDrawing.jsonProperties.displaySpatialView,
+                        drawingToSpatialTransform: sectionDrawing.jsonProperties.drawingToSpatialTransform,
+                    };
                 }
             }
-            return viewStateData;
+            return props;
         }
         /** @deprecated in 3.x. use [[getViewStateProps]]. */
         getViewStateData(viewDefinitionId, options) {
-            const view = this._iModel.elements.getElement(viewDefinitionId);
-            let drawingExtents;
-            if (view instanceof ViewDefinition_1.DrawingViewDefinition) {
-                try {
-                    drawingExtents = core_geometry_1.Range3d.fromJSON(this._iModel.nativeDb.queryModelExtents({ id: view.baseModelId }).modelExtents);
-                }
-                catch {
-                    //
-                }
+            const viewStateData = this.loadViewData(viewDefinitionId, options);
+            const baseModelId = viewStateData.viewDefinitionProps.baseModelId;
+            if (baseModelId) {
+                const drawingExtents = core_geometry_1.Range3d.fromJSON(this._iModel.nativeDb.queryModelExtents({ id: baseModelId }).modelExtents);
+                if (!drawingExtents.isNull)
+                    viewStateData.modelExtents = drawingExtents.toJSON();
             }
-            return this.loadViewStateProps(view, options, drawingExtents);
+            return viewStateData;
         }
-        /** Obtain a [ViewStateProps]($common) for a [[ViewDefinition]] specified by element Id. */
+        /** Obtain a [ViewStateProps]($common) for a [[ViewDefinition]] specified by ViewIdString. */
         async getViewStateProps(viewDefinitionId, options) {
-            const view = this._iModel.elements.getElement(viewDefinitionId);
-            let drawingExtents;
-            if (view instanceof ViewDefinition_1.DrawingViewDefinition)
-                drawingExtents = (await this._iModel.models.queryRange(view.baseModelId));
-            return this.loadViewStateProps(view, options, drawingExtents);
+            const viewStateData = this.loadViewData(viewDefinitionId, options);
+            const baseModelId = viewStateData.viewDefinitionProps.baseModelId;
+            if (baseModelId) {
+                const drawingExtents = await this._iModel.models.queryRange(baseModelId);
+                if (!drawingExtents.isNull)
+                    viewStateData.modelExtents = drawingExtents.toJSON();
+            }
+            return viewStateData;
         }
         getViewThumbnailArg(viewDefinitionId) {
+            if (!core_bentley_1.Id64.isValid(viewDefinitionId))
+                throw new Error("illegal thumbnail id");
             return { namespace: "dgn_View", name: "Thumbnail", id: viewDefinitionId };
         }
         /** Get the thumbnail for a view.
@@ -1890,13 +1940,14 @@ exports.IModelDb = IModelDb;
             this._iModel.saveFileProperty(spec, undefined, blob8);
         }
     }
+    Views.viewStoreProperty = { namespace: "itwinjs", name: "DefaultViewStore" };
     /** Default parameters for iterating/querying ViewDefinitions. Includes all subclasses of ViewDefinition, excluding only those marked 'private'. */
     Views.defaultQueryParams = { from: "BisCore.ViewDefinition", where: "IsPrivate=FALSE" };
     IModelDb.Views = Views;
     /** Represents the current state of a pollable tile content request.
-     * Note: lack of a "completed" state because polling a completed request returns the content as a Uint8Array.
-     * @internal
-     */
+   * Note: lack of a "completed" state because polling a completed request returns the content as a Uint8Array.
+   * @internal
+   */
     let TileContentState;
     (function (TileContentState) {
         TileContentState[TileContentState["New"] = 0] = "New";
@@ -2008,6 +2059,8 @@ class BriefcaseDb extends IModelDb {
         super({ ...args, changeset: args.nativeDb.getCurrentChangeset() });
         /** Manages local changes to this briefcase. */
         this.txns = new TxnManager_1.TxnManager(this);
+        /** Event raised after a BriefcaseDb has been closed. */
+        this.onClosed = new core_bentley_1.BeEvent();
         this._openMode = args.openMode;
         this.briefcaseId = args.briefcaseId;
         if (this.useLockServer) // if the iModel uses a lock server, create a ServerBasedLocks LockControl for this BriefcaseDb.
@@ -2054,9 +2107,16 @@ class BriefcaseDb extends IModelDb {
     static async open(args) {
         this.onOpen.raiseEvent(args);
         const file = { path: args.fileName, key: args.key };
-        const openMode = args.readonly ? core_bentley_1.OpenMode.Readonly : core_bentley_1.OpenMode.ReadWrite;
+        const openMode = (args.readonly || args.watchForChanges) ? core_bentley_1.OpenMode.Readonly : core_bentley_1.OpenMode.ReadWrite;
         const nativeDb = this.openDgnDb(file, openMode, undefined, args);
         const briefcaseDb = new BriefcaseDb({ nativeDb, key: file.key ?? core_bentley_1.Guid.createValue(), openMode, briefcaseId: nativeDb.getBriefcaseId() });
+        // If they asked to watch for changes, set an fs.watch on the "-wal" file (only it is modified while we hold this connection.)
+        // Whenever there are changes, restart our defaultTxn. That loads the changes from the other connection and sends
+        // notifications as if they happened on this connection. Note: the watcher is called only when the backend event loop cycles.
+        if (args.watchForChanges && undefined === args.container) {
+            const watcher = fs.watch(`${file.path}-wal`, { persistent: false }, () => nativeDb.restartDefaultTxn());
+            briefcaseDb.onBeforeClose.addOnce(() => watcher.close()); // Stop the watcher when we close this connection.
+        }
         if (openMode === core_bentley_1.OpenMode.ReadWrite && CodeService_1.CodeService.createForIModel) {
             try {
                 briefcaseDb._codeService = await CodeService_1.CodeService.createForIModel(briefcaseDb);
@@ -2067,7 +2127,6 @@ class BriefcaseDb extends IModelDb {
                     throw e;
             }
         }
-        BriefcaseManager_1.BriefcaseManager.logUsage(briefcaseDb);
         this.onOpened.raiseEvent(briefcaseDb, args);
         return briefcaseDb;
     }
@@ -2103,6 +2162,10 @@ class BriefcaseDb extends IModelDb {
         const changeset = this.changeset;
         IpcHost_1.IpcHost.notifyTxns(this, "notifyPushedChanges", changeset);
     }
+    close() {
+        super.close();
+        this.onClosed.raiseEvent();
+    }
 }
 /**
  * Event raised just before a BriefcaseDb is opened. Supplies the arguments that will be used to open the BriefcaseDb.
@@ -2250,10 +2313,13 @@ class SnapshotDb extends IModelDb {
      * @throws [[IModelError]] If the file is not found or is not a valid *snapshot*.
      */
     static openFile(path, opts) {
+        this.onOpen.raiseEvent(path, opts);
         const file = { path, key: opts?.key };
         const nativeDb = this.openDgnDb(file, core_bentley_1.OpenMode.Readonly, undefined, opts);
         (0, core_bentley_1.assert)(undefined !== file.key);
-        return new SnapshotDb(nativeDb, file.key);
+        const db = new SnapshotDb(nativeDb, file.key);
+        this.onOpened.raiseEvent(db);
+        return db;
     }
     /** Open a previously downloaded V1 checkpoint file.
      * @note The key is generated by this call is predictable and is formed from the IModelId and ChangeSetId.
@@ -2310,6 +2376,8 @@ class SnapshotDb extends IModelDb {
         }
     }
 }
+SnapshotDb.onOpen = new core_bentley_1.BeEvent();
+SnapshotDb.onOpened = new core_bentley_1.BeEvent();
 exports.SnapshotDb = SnapshotDb;
 /**
  * Standalone iModels are read/write files that are not associated with an iTwin or managed by iModelHub.
@@ -2364,6 +2432,19 @@ class StandaloneDb extends BriefcaseDb {
         nativeDb = this.openDgnDb({ path: filePath }, core_bentley_1.OpenMode.ReadWrite, { domain: core_common_1.DomainOptions.Upgrade, schemaLockHeld: true });
         nativeDb.closeIModel();
     }
+    /** Creates or updates views in the iModel to permit visualizing the EC content as ECClasses and ECProperties rather than raw database tables and columns.
+     * This can be helpful when debugging the EC data, especially when the raw tables make use of shared columns or spread data across multiple tables.
+     * @throws IModelError if view creation failed.
+     * @note The views are strictly intended for developers and debugging purposes only - they should not be used in application code.
+     * @beta
+     */
+    createClassViews() {
+        const result = this.nativeDb.createClassViewsInDb();
+        if (core_bentley_1.BentleyStatus.SUCCESS !== result)
+            throw new core_common_1.IModelError(result, "Error creating class views");
+        else
+            this.saveChanges();
+    }
     /** Open a standalone iModel file.
      * @param filePath The path of the standalone iModel file.
      * @param openMode Optional open mode for the standalone iModel. The default is read/write.