@itwin/core-backend 3.0.0-dev.100

package/lib/cjs/ServerBasedLocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerBasedLocks.js","sourceRoot":"","sources":["../../src/ServerBasedLocks.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n\r\n/** @packageDocumentation\r\n * @module iModels\r\n */\r\n\r\nimport { DbResult, Id64, Id64Arg, Id64String, IModelStatus, OpenMode } from \"@itwin/core-bentley\";\r\nimport { IModel, IModelError } from \"@itwin/core-common\";\r\nimport { LockMap, LockState } from \"./BackendHubAccess\";\r\nimport { BriefcaseDb, LockControl } from \"./IModelDb\";\r\nimport { IModelHost } from \"./IModelHost\";\r\nimport { SQLiteDb } from \"./SQLiteDb\";\r\n\r\n/**\r\n * Both the Model and Parent of an element are considered \"owners\" of their member elements. That means:\r\n * 1) they must hold at least a shared lock before an exclusive lock can be acquired for their members\r\n * 2) if they hold an exclusive lock, then all of their members are exclusively locked implicitly.\r\n * @internal\r\n */\r\nexport interface ElementOwners {\r\n  readonly modelId: Id64String;\r\n  readonly parentId: Id64String | undefined;\r\n}\r\n\r\n// eslint-disable-next-line no-restricted-syntax\r\nconst enum LockOrigin {\r\n  Acquired = 0,\r\n  NewElement = 1,\r\n  Discovered = 2,\r\n}\r\n\r\n/** @internal */\r\nexport class ServerBasedLocks implements LockControl {\r\n  public get isServerBased() { return true; }\r\n  protected readonly lockDb = new SQLiteDb();\r\n  protected readonly briefcase: BriefcaseDb;\r\n\r\n  public constructor(iModel: BriefcaseDb) {\r\n    this.briefcase = iModel;\r\n    const dbName = `${iModel.nativeDb.getTempFileBaseName()}-locks`;\r\n    try {\r\n      this.lockDb.openDb(dbName, OpenMode.ReadWrite);\r\n    } catch (_e) {\r\n      this.lockDb.createDb(dbName);\r\n      this.lockDb.executeSQL(\"CREATE TABLE locks(id INTEGER PRIMARY KEY NOT NULL,state INTEGER NOT NULL,origin INTEGER)\");\r\n      this.lockDb.saveChanges();\r\n    }\r\n  }\r\n\r\n  public close() {\r\n    if (this.lockDb.isOpen)\r\n      this.lockDb.closeDb();\r\n  }\r\n\r\n  private getOwners(id: Id64String): ElementOwners {\r\n    return this.briefcase.withPreparedSqliteStatement(\"SELECT ModelId,ParentId FROM bis_Element WHERE id=?\", (stmt) => {\r\n      stmt.bindId(1, id);\r\n      const rc = stmt.step();\r\n      if (DbResult.BE_SQLITE_ROW !== rc)\r\n        throw new IModelError(rc, `element ${id} not found`);\r\n\r\n      return { modelId: stmt.getValueId(0), parentId: stmt.getValueId(1) };\r\n    });\r\n  }\r\n\r\n  private getLockState(id?: Id64String): LockState | undefined {\r\n    return (id === undefined || !Id64.isValid(id)) ? undefined : this.lockDb.withPreparedSqliteStatement(\"SELECT state FROM locks WHERE id=?\", (stmt) => {\r\n      stmt.bindId(1, id);\r\n      return (DbResult.BE_SQLITE_ROW === stmt.step()) ? stmt.getValueInteger(0) : undefined;\r\n    });\r\n  }\r\n\r\n  /** Clear the cache of locally held locks.\r\n   * Note: does *not* release locks from server.\r\n   */\r\n  private clearAllLocks() {\r\n    this.lockDb.executeSQL(\"DELETE FROM locks\");\r\n    this.lockDb.saveChanges();\r\n  }\r\n\r\n  /** only for tests */\r\n  public getLockCount(state: LockState): number {\r\n    return this.lockDb.withSqliteStatement(\"SELECT count(*) FROM locks WHERE state=?\", (stmt) => {\r\n      stmt.bindInteger(1, state);\r\n      stmt.step();\r\n      return stmt.getValueInteger(0);\r\n    });\r\n  }\r\n\r\n  public async releaseAllLocks(): Promise<void> {\r\n    await IModelHost.hubAccess.releaseAllLocks(this.briefcase); // throws if unsuccessful\r\n    this.clearAllLocks();\r\n  }\r\n\r\n  private insertLock(id: Id64String, state: LockState, origin: LockOrigin): true {\r\n    this.lockDb.withPreparedSqliteStatement(\"INSERT INTO locks(id,state,origin) VALUES (?,?,?) ON CONFLICT(id) DO UPDATE SET state=excluded.state,origin=excluded.origin\", (stmt) => {\r\n      stmt.bindId(1, id);\r\n      stmt.bindInteger(2, state);\r\n      stmt.bindInteger(3, origin);\r\n      const rc = stmt.step();\r\n      if (DbResult.BE_SQLITE_DONE !== rc)\r\n        throw new IModelError(rc, \"can't insert lock into database\");\r\n    });\r\n    return true;\r\n  }\r\n\r\n  private ownerHoldsExclusiveLock(id: Id64String | undefined): boolean {\r\n    if (id === undefined || id === IModel.rootSubjectId)\r\n      return false; // has no owners\r\n\r\n    const { modelId, parentId } = this.getOwners(id);\r\n    if (this.getLockState(modelId) === LockState.Exclusive || this.getLockState(parentId) === LockState.Exclusive)\r\n      return true;\r\n\r\n    // see if this model is exclusively locked by one of its owners. If so, save that fact on modelId so future tests won't have to descend.\r\n    if (this.ownerHoldsExclusiveLock(modelId))\r\n      return this.insertLock(modelId, LockState.Exclusive, LockOrigin.Discovered);\r\n\r\n    // see if the parent is exclusively locked by one of its owners. If so, save that fact on parentId so future tests won't have to descend.\r\n    return this.ownerHoldsExclusiveLock(parentId) ? this.insertLock(parentId!, LockState.Exclusive, LockOrigin.Discovered) : false;\r\n  }\r\n\r\n  /** Determine whether an the exclusive lock is already held by an element (or one of its owners) */\r\n  public holdsExclusiveLock(id: Id64String): boolean {\r\n    // see if we hold the exclusive lock. or if one of the element's owners is exclusively locked (recursively)\r\n    return this.getLockState(id) === LockState.Exclusive || this.ownerHoldsExclusiveLock(id);\r\n  }\r\n\r\n  public holdsSharedLock(id: Id64String): boolean {\r\n    const state = this.getLockState(id);\r\n    // see if we hold shared or exclusive lock, or if an owner has exclusive lock. If so we implicitly have shared lock, but owner holding shared lock doesn't help.\r\n    return (state === LockState.Shared || state === LockState.Exclusive) || this.ownerHoldsExclusiveLock(id);\r\n  }\r\n\r\n  /** if the shared lock on the element supplied is not already held, add it to the set of shared locks required. Then, check owners. */\r\n  private addSharedLock(id: Id64String | undefined, locks: Set<Id64String>) {\r\n    // if the id is not valid, or of the lock is already in the set, or if we already hold a shared lock, we're done\r\n    // Note: if we hold a shared lock, it is guaranteed that we also hold all required shared locks on owners.\r\n    if (id === undefined || !Id64.isValid(id) || locks.has(id) || this.holdsSharedLock(id))\r\n      return;\r\n\r\n    locks.add(id); // add to set of needed shared locks\r\n    this.addOwnerSharedLocks(id, locks); // check parent models and groups\r\n  }\r\n\r\n  /** add owners (recursively) of an element to a list of required shared locks, if not already held. */\r\n  private addOwnerSharedLocks(id: Id64String, locks: Set<Id64String>) {\r\n    const el = this.getOwners(id);\r\n    this.addSharedLock(el.parentId, locks); // if this element is in a group\r\n    this.addSharedLock(el.modelId, locks); // check its model\r\n  }\r\n\r\n  /** attempt to acquire all necessary locks for a set of elements */\r\n  private async acquireAllLocks(locks: LockMap) {\r\n    if (locks.size === 0) // no locks are required.\r\n      return;\r\n\r\n    const sharedLocks = new Set<Id64String>();\r\n    for (const lock of locks)\r\n      this.addOwnerSharedLocks(lock[0], sharedLocks);\r\n\r\n    for (const shared of sharedLocks) {\r\n      if (!locks.has(shared)) // we may already be asking for exclusive lock\r\n        locks.set(shared, LockState.Shared);\r\n    }\r\n\r\n    await IModelHost.hubAccess.acquireLocks(this.briefcase, locks); // throws if unsuccessful\r\n    for (const lock of locks)\r\n      this.insertLock(lock[0], lock[1], LockOrigin.Acquired);\r\n    this.lockDb.saveChanges();\r\n  }\r\n\r\n  /**\r\n   * Acquire the exclusive lock on one or more elements. This also attempts to acquire a shared lock on all of the element's owners, recursively.\r\n   * If *any* lock cannot be obtained, no locks are acquired.\r\n   */\r\n  public async acquireExclusiveLock(ids: Id64Arg): Promise<void> {\r\n    const locks = new Map<Id64String, LockState>();\r\n    for (const id of Id64.iterable(ids)) {\r\n      if (!this.holdsExclusiveLock(id))\r\n        locks.set(id, LockState.Exclusive);\r\n    }\r\n    return this.acquireAllLocks(locks);\r\n  }\r\n\r\n  /**\r\n   * Acquire a shared lock on one or more elements. This also attempts to acquire a shared lock on all of the element's owners, recursively.\r\n   * If *any* lock cannot be obtained, no locks are acquired.\r\n   */\r\n  public async acquireSharedLock(ids: Id64Arg): Promise<void> {\r\n    const locks = new Map<Id64String, LockState>();\r\n    for (const id of Id64.iterable(ids)) {\r\n      if (!this.holdsSharedLock(id))\r\n        locks.set(id, LockState.Shared);\r\n    }\r\n    return this.acquireAllLocks(locks);\r\n  }\r\n\r\n  /** When an element is newly created in a session, we hold the lock on it implicitly. Save that fact. */\r\n  public elementWasCreated(id: Id64String) {\r\n    this.insertLock(id, LockState.Exclusive, LockOrigin.NewElement);\r\n    this.lockDb.saveChanges();\r\n  }\r\n\r\n  /** locks are not necessary during change propagation. */\r\n  private get _locksAreRequired() { return !this.briefcase.txns.isIndirectChanges; }\r\n\r\n  /** throw if locks are currently required and the exclusive lock is not held on the supplied element */\r\n  public checkExclusiveLock(id: Id64String, type: string, operation: string) {\r\n    if (this._locksAreRequired && !this.holdsExclusiveLock(id))\r\n      throw new IModelError(IModelStatus.LockNotHeld, `exclusive lock not held on ${type} for ${operation} (id=${id})`);\r\n  }\r\n\r\n  /** throw if locks are currently required and a shared lock is not held on the supplied element */\r\n  public checkSharedLock(id: Id64String, type: string, operation: string) {\r\n    if (this._locksAreRequired && !this.holdsSharedLock(id))\r\n      throw new IModelError(IModelStatus.LockNotHeld, `shared lock not held on ${type} for ${operation} (id=${id})`);\r\n  }\r\n\r\n}\r\n\r\n"]}

package/lib/cjs/SqliteStatement.d.ts

@@ -0,0 +1,264 @@
+/** @packageDocumentation
+ * @module SQLite
+ */
+import { DbResult, GuidString, Id64String, IDisposable } from "@itwin/core-bentley";
+import { IModelJsNative } from "@bentley/imodeljs-native";
+/** Marks a string as either an [Id64String]($core-bentley) or [GuidString]($core-bentley), so
+ * that it can be passed to the [bindValue]($backend.SqliteStatement) or [bindValues]($backend.SqliteStatement)
+ * methods of [SqliteStatement]($backend).
+ * @internal
+ */
+export interface StringParam {
+    id?: Id64String;
+    guid?: GuidString;
+}
+/** parameter Index (1-based), or name of the parameter (including the initial ':', '@' or '$')
+ * @public
+ */
+export declare type BindParameter = number | string;
+/** Executes SQLite SQL statements.
+ *
+ * A statement must be prepared before it can be executed, and it must be released when no longer needed.
+ * See [IModelDb.withPreparedSqliteStatement]($backend) or
+ * [ECDb.withPreparedSqliteStatement]($backend) for a convenient and
+ * reliable way to prepare, execute, and then release a statement.
+ *
+ * A statement may contain parameters that must be filled in before use by calling [SqliteStatement.bindValue]($backend)
+ * or [SqliteStatement.bindValues]($backend).
+ *
+ * Once prepared (and parameters are bound, if any), the statement is executed by calling [SqliteStatement.step]($backend).
+ * In case of an **SQL SELECT** statement, the current row can be retrieved with [SqliteStatement.getRow]($backend) as
+ * a whole, or with [SqliteStatement.getValue]($backend) when individual values are needed.
+ * Alternatively, query results of an **SQL SELECT** statement can be stepped through by using
+ * standard iteration syntax, such as `for of`.
+ *
+ * > Preparing a statement can be time-consuming. The best way to reduce the effect of this overhead is to cache and reuse prepared
+ * > statements. A cached prepared statement may be used in different places in an app, as long as the statement is general enough.
+ * > The key to making this strategy work is to phrase a statement in a general way and use placeholders to represent parameters that will vary on each use.
+ * @public
+ */
+export declare class SqliteStatement implements IterableIterator<any>, IDisposable {
+    private _sql;
+    private _stmt;
+    constructor(_sql: string);
+    get stmt(): IModelJsNative.SqliteStatement | undefined;
+    get sql(): string;
+    /** Check if this statement has been prepared successfully or not */
+    get isPrepared(): boolean;
+    /** Prepare this statement prior to first use.
+     * @param db The DgnDb or ECDb to prepare the statement against
+     * @param sql The SQL statement string to prepare
+     * @param logErrors Determine if errors are logged or not
+     * @throws if the SQL statement cannot be prepared. Normally, prepare fails due to SQL syntax errors or references to tables or properties that do not exist.
+     * The error.message property will provide details.
+     */
+    prepare(db: IModelJsNative.DgnDb | IModelJsNative.ECDb | IModelJsNative.SQLiteDb, logErrors?: boolean): void;
+    /** Indicates whether the prepared statement makes no **direct* changes to the content of the file
+     * or not. See [SQLite docs](https://www.sqlite.org/c3ref/stmt_readonly.html) for details.
+     */
+    get isReadonly(): boolean;
+    /** Reset this statement so that the next call to step will return the first row, if any.
+     */
+    reset(): void;
+    /** Call this function when finished with this statement. This releases the native resources held by the statement. */
+    dispose(): void;
+    /** Binds a value to the specified SQL parameter.
+     *  The value must be of one of these types:
+     *  JavaScript Type | SQLite Type
+     *  --- | ---
+     *  undefined | NULL
+     *  boolean | INTEGER with true being bound as 1 and false as 0
+     *  number | INTEGER if number is integral or REAL if number is not integral
+     *  string | TEXT
+     *  Uint8Array or ArrayBuffer | BLOB
+     *  [StringParam]($backend) where member **id** is set | INTEGER
+     *  [StringParam]($backend) where member **guid** is set | BLOB
+     *
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param value Value to bind.
+     *  @throws [IModelError]($common) if the value is of an unsupported type or in
+     *  case of other binding errors.
+     */
+    bindValue(parameter: BindParameter, value: any): void;
+    private checkBind;
+    /** Bind an integer parameter
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param val integer to bind.
+     */
+    bindInteger(parameter: BindParameter, val: number): void;
+    /** Bind a double parameter
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param val double to bind.
+     */
+    bindDouble(parameter: BindParameter, val: number): void;
+    /** Bind a string parameter
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param val string to bind.
+     */
+    bindString(parameter: BindParameter, val: string): void;
+    /** Bind an Id64String parameter as a 64-bit integer
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param val Id to bind.
+     */
+    bindId(parameter: BindParameter, id: Id64String): void;
+    /** Bind a Guid parameter
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param val Guid to bind.
+     */
+    bindGuid(parameter: BindParameter, guid: GuidString): void;
+    /** Bind a blob parameter
+     *  @param parameter Index (1-based) or name of the parameter (including the initial ':', '@' or '$')
+     *  @param val blob to bind.
+     */
+    bindBlob(parameter: BindParameter, blob: Uint8Array): void;
+    /** Bind values to all parameters in the statement.
+     * @param values The values to bind to the parameters.
+     * Pass an *array* of values if the parameters are *positional*.
+     * Pass an *object of the values keyed on the parameter name* for *named parameters*.
+     * The values in either the array or object must match the respective types of the parameter.
+     * See [[SqliteStatement.bindValue]] for details on the supported types.
+     */
+    bindValues(values: any[] | object): void;
+    /** Clear any bindings that were previously set on this statement.
+     * @throws [IModelError]($common) in case of errors
+     */
+    clearBindings(): void;
+    /** Step this statement to the next row.
+     *
+     *  For **SQL SELECT** statements the method returns
+     *  - [DbResult.BE_SQLITE_ROW]($core-bentley) if the statement now points successfully to the next row.
+     *  - [DbResult.BE_SQLITE_DONE]($core-bentley) if the statement has no more rows.
+     *  - Error status in case of errors.
+     *
+     *  For **SQL INSERT, UPDATE, DELETE** statements the method returns
+     *  - [DbResult.BE_SQLITE_DONE]($core-bentley) if the statement has been executed successfully.
+     *  - Error status in case of errors.
+     */
+    step(): DbResult;
+    /** Get the query result's column count (only for SQL SELECT statements). */
+    getColumnCount(): number;
+    /** Get the value for the column at the given index in the query result.
+     * @param columnIx Index of SQL column in query result (0-based)
+     */
+    getValue(columnIx: number): SqliteValue;
+    /** Get a value as a blob
+     * @param colIndex Index of SQL column in query result (0-based)
+     */
+    getValueBlob(colIndex: number): Uint8Array;
+    /** Get a value as a double
+    * @param colIndex Index of SQL column in query result (0-based)
+    */
+    getValueDouble(colIndex: number): number;
+    /** Get a value as a integer
+    * @param colIndex Index of SQL column in query result (0-based)
+    */
+    getValueInteger(colIndex: number): number;
+    /** Get a value as a string
+    * @param colIndex Index of SQL column in query result (0-based)
+    */
+    getValueString(colIndex: number): string;
+    /** Get a value as an Id
+    * @param colIndex Index of SQL column in query result (0-based)
+    */
+    getValueId(colIndex: number): Id64String;
+    /** Get a value as a Guid
+    * @param colIndex Index of SQL column in query result (0-based)
+    */
+    getValueGuid(colIndex: number): GuidString;
+    /** Get the current row.
+     * The returned row is formatted as JavaScript object where every SELECT clause item becomes a property in the JavaScript object.
+     *
+     * The SQL select clause item's name becomes the member name of the JavaScript object, **with the first character lowered**.
+     *
+     * SQLite Type | JavaScript Type
+     * --- | ---
+     * [SqliteValueType.Null]($backend) | undefined
+     * [SqliteValueType.Integer]($backend) | number
+     * [SqliteValueType.Double]($backend) | number
+     * [SqliteValueType.String]($backend) | string
+     * [SqliteValueType.Blob]($backend) | Uint8Array
+     */
+    getRow(): any;
+    private static determineResultRowPropertyName;
+    /** Calls step when called as an iterator.
+     */
+    next(): IteratorResult<any>;
+    /** The iterator that will step through the results of this statement. */
+    [Symbol.iterator](): IterableIterator<any>;
+}
+/** Data type of a value in in an SQLite SQL query result.
+ * See also:
+ * - [SqliteValue]($backend)
+ * - [SqliteStatement]($backend)
+ * - [SqliteStatement.getValue]($backend)
+ * @public
+ */
+export declare enum SqliteValueType {
+    Integer = 1,
+    Double = 2,
+    String = 3,
+    Blob = 4,
+    Null = 5
+}
+/** Value of a column in a row of an SQLite SQL query result.
+ * See also:
+ * - [SqliteStatement]($backend)
+ * - [SqliteStatement.getValue]($backend)
+ * @public
+ */
+export declare class SqliteValue {
+    private readonly _stmt;
+    private readonly _colIndex;
+    constructor(stmt: IModelJsNative.SqliteStatement, colIndex: number);
+    /** Indicates whether the value is NULL or not. */
+    get isNull(): boolean;
+    /** Gets the data type of the value. */
+    get type(): SqliteValueType;
+    /** Gets the name of the column of the value. */
+    get columnName(): string;
+    /** Gets the SqlValue as JavaScript value.
+     *
+     * SQLite Type | JavaScript Type
+     * --- | ---
+     * [SqliteValueType.Null]($backend) | undefined
+     * [SqliteValueType.Integer]($backend) | number
+     * [SqliteValueType.Double]($backend) | number
+     * [SqliteValueType.String]($backend) | string
+     * [SqliteValueType.Blob]($backend) | Uint8Array
+     */
+    get value(): any;
+    /** Get the value as BLOB */
+    getBlob(): Uint8Array;
+    /** Get the value as a double value */
+    getDouble(): number;
+    /** Get the value as a integer value */
+    getInteger(): number;
+    /** Get the value as a string value */
+    getString(): string;
+    /** Get the value as an Id value */
+    getId(): Id64String;
+    /** Get the value as a Guid value */
+    getGuid(): GuidString;
+}
+interface Statement {
+    isPrepared: boolean;
+    sql: string;
+    dispose(): void;
+    reset(): void;
+    clearBindings(): void;
+}
+/** A cache for previously prepared SqliteStatements.
+ * It only holds Statements after they are no longer in use, resetting and clearing their bindings before saving them.
+ * When a request to use a statement from the cache is made, it is first removed from the cache.
+ * @internal
+ */
+export declare class StatementCache<Stmt extends Statement> {
+    private _cache;
+    constructor(maxCount?: number);
+    get size(): number;
+    addOrDispose(stmt: Stmt): void;
+    findAndRemove(sql: string): Stmt | undefined;
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=SqliteStatement.d.ts.map

package/lib/cjs/SqliteStatement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteStatement.d.ts","sourceRoot":"","sources":["../../src/SqliteStatement.ts"],"names":[],"mappings":"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"}