@itwin/ecschema-metadata 4.8.0-dev.9 → 4.9.0-dev.1

package/lib/esm/Metadata/Schema.js

@@ -0,0 +1,570 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Metadata
+ */
+import { SchemaReadHelper } from "../Deserialization/Helper";
+import { JsonParser } from "../Deserialization/JsonParser";
+import { XmlSerializationUtils } from "../Deserialization/XmlSerializationUtils";
+import { ECObjectsError, ECObjectsStatus } from "../Exception";
+import { ECVersion, SchemaItemKey, SchemaKey } from "../SchemaKey";
+import { ECName } from "../ECName";
+import { ECClass, StructClass } from "./Class";
+import { Constant } from "./Constant";
+import { serializeCustomAttributes } from "./CustomAttribute";
+import { CustomAttributeClass } from "./CustomAttributeClass";
+import { EntityClass } from "./EntityClass";
+import { Enumeration } from "./Enumeration";
+import { Format } from "./Format";
+import { InvertedUnit } from "./InvertedUnit";
+import { KindOfQuantity } from "./KindOfQuantity";
+import { Mixin } from "./Mixin";
+import { Phenomenon } from "./Phenomenon";
+import { PropertyCategory } from "./PropertyCategory";
+import { RelationshipClass } from "./RelationshipClass";
+import { SchemaItem } from "./SchemaItem";
+import { Unit } from "./Unit";
+import { UnitSystem } from "./UnitSystem";
+const SCHEMAURL3_2_JSON = "https://dev.bentley.com/json_schemas/ec/32/ecschema";
+const SCHEMAURL3_2_XML = "http://www.bentley.com/schemas/Bentley.ECXML.3.2";
+/**
+ * @beta
+ */
+export class Schema {
+    /** @internal */
+    constructor(context, nameOrKey, alias, readVer, writeVer, minorVer) {
+        this._schemaKey = (typeof (nameOrKey) === "string") ? new SchemaKey(nameOrKey, new ECVersion(readVer, writeVer, minorVer)) : nameOrKey;
+        this._context = context;
+        this.references = [];
+        this._items = new Map();
+        if (alias !== undefined && ECName.validate(alias)) {
+            this._alias = alias;
+        }
+        else if (nameOrKey !== undefined) {
+            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The Schema ${this.name} does not have the required 'alias' attribute.`);
+        }
+    }
+    get schemaKey() {
+        if (undefined === this._schemaKey)
+            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The schema '${this.name}' has an invalid SchemaKey.`);
+        return this._schemaKey;
+    }
+    get name() { return this.schemaKey.name; }
+    get readVersion() { return this.schemaKey.readVersion; }
+    get writeVersion() { return this.schemaKey.writeVersion; }
+    get minorVersion() { return this.schemaKey.minorVersion; }
+    get alias() {
+        if (this._alias === undefined || this._alias === null) {
+            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The Schema ${this.name} does not have the required 'alias' attribute.`);
+        }
+        else {
+            return this._alias;
+        }
+    }
+    get label() { return this._label; }
+    get description() { return this._description; }
+    get customAttributes() { return this._customAttributes; }
+    /** Returns the schema name. */
+    get fullName() { return this.schemaKey.name; }
+    /** Returns the schema. */
+    get schema() { return this; }
+    /** Returns the schema context this schema is within. */
+    get context() { return this._context; }
+    /**
+     * Returns a SchemaItemKey given the item name and the schema it belongs to
+     * @param fullName fully qualified name {Schema name}.{Item Name}
+     */
+    getSchemaItemKey(fullName) {
+        const [schemaName, itemName] = SchemaItem.parseFullName(fullName);
+        let schemaKey = this.schemaKey;
+        if (this.name !== schemaName) {
+            const newSchemaRef = this.getReferenceSync(schemaName);
+            if (undefined === newSchemaRef)
+                throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `Unable to find the referenced SchemaItem ${itemName}.`);
+            schemaKey = newSchemaRef.schemaKey;
+        }
+        return new SchemaItemKey(itemName, schemaKey);
+    }
+    addItem(item) {
+        if (undefined !== this.getItemSync(item.name))
+            throw new ECObjectsError(ECObjectsStatus.DuplicateItem, `The SchemaItem ${item.name} cannot be added to the schema ${this.name} because it already exists`);
+        this._items.set(item.name.toUpperCase(), item);
+    }
+    /**
+     * @alpha
+     */
+    createClass(type, name, modifier) {
+        const item = new type(this, name, modifier);
+        this.addItem(item);
+        return item;
+    }
+    /**
+     * Deletes a class from within this schema.
+     * @param name the local (unqualified) class name, lookup is case-insensitive
+     * @alpha
+     */
+    async deleteClass(name) {
+        const schemaItem = await this.getItem(name);
+        if (ECClass.isECClass(schemaItem)) {
+            this._items.delete(name.toUpperCase());
+        }
+    }
+    /**
+     * Deletes a class from within this schema.
+     * @param name the local (unqualified) class name, lookup is case-insensitive
+     * @alpha
+     */
+    deleteClassSync(name) {
+        const schemaItem = this.getItemSync(name);
+        if (ECClass.isECClass(schemaItem))
+            this._items.delete(name.toUpperCase());
+    }
+    /**
+     * Deletes a SchemaItem from within this schema.
+     * @param name the local (unqualified) class name, lookup is case-insensitive
+     * @alpha
+     */
+    async deleteSchemaItem(name) {
+        const schemaItem = await this.getItem(name);
+        if (SchemaItem.isSchemaItem(schemaItem)) {
+            this._items.delete(name.toUpperCase());
+        }
+    }
+    /**
+     * Deletes a SchemaItem from within this schema.
+     * @param name the local (unqualified) class name, lookup is case-insensitive
+     * @alpha
+     */
+    deleteSchemaItemSync(name) {
+        const schemaItem = this.getItemSync(name);
+        if (SchemaItem.isSchemaItem(schemaItem))
+            this._items.delete(name.toUpperCase());
+    }
+    /**
+     * @alpha
+     */
+    createItem(type, name) {
+        const item = new type(this, name);
+        this.addItem(item);
+        return item;
+    }
+    addCustomAttribute(customAttribute) {
+        if (!this._customAttributes)
+            this._customAttributes = new Map();
+        this._customAttributes.set(customAttribute.className, customAttribute);
+    }
+    /**
+     * Creates a EntityClass with the provided name in this schema.
+     * @param name
+     * @param modifier
+     */
+    async createEntityClass(name, modifier) {
+        return this.createClass(EntityClass, name, modifier);
+    }
+    createEntityClassSync(name, modifier) {
+        return this.createClass(EntityClass, name, modifier);
+    }
+    /**
+     * Creates a Mixin with the provided name in this schema.
+     * @param name
+     */
+    async createMixinClass(name) { return this.createClass(Mixin, name); }
+    createMixinClassSync(name) { return this.createClass(Mixin, name); }
+    /**
+     * Creates a StructClass with the provided name in this schema.
+     * @param name
+     * @param modifier
+     */
+    async createStructClass(name, modifier) {
+        return this.createClass(StructClass, name, modifier);
+    }
+    createStructClassSync(name, modifier) {
+        return this.createClass(StructClass, name, modifier);
+    }
+    /**
+     * Creates a CustomAttributeClass with the provided name in this schema.
+     * @param name
+     * @param modifier
+     */
+    async createCustomAttributeClass(name, modifier) {
+        return this.createClass(CustomAttributeClass, name, modifier);
+    }
+    createCustomAttributeClassSync(name, modifier) {
+        return this.createClass(CustomAttributeClass, name, modifier);
+    }
+    /**
+     * Creates a RelationshipClass with the provided name in this schema.
+     * @param name
+     * @param modifier
+     */
+    async createRelationshipClass(name, modifier) {
+        return this.createRelationshipClassSync(name, modifier);
+    }
+    createRelationshipClassSync(name, modifier) {
+        return this.createClass(RelationshipClass, name, modifier);
+    }
+    /**
+     * Creates an Enumeration with the provided name in this schema.
+     * @param name
+     */
+    async createEnumeration(name, primitiveType) {
+        return this.createEnumerationSync(name, primitiveType);
+    }
+    createEnumerationSync(name, primitiveType) {
+        const item = new Enumeration(this, name, primitiveType);
+        this.addItem(item);
+        return item;
+    }
+    /**
+     * Creates an KindOfQuantity with the provided name in this schema.
+     * @param name
+     */
+    async createKindOfQuantity(name) {
+        return this.createKindOfQuantitySync(name);
+    }
+    createKindOfQuantitySync(name) {
+        return this.createItem(KindOfQuantity, name);
+    }
+    /**
+     * Creates a Constant with the provided name in this schema.
+     * @param name
+     */
+    async createConstant(name) {
+        return this.createItem(Constant, name);
+    }
+    createConstantSync(name) {
+        return this.createItem(Constant, name);
+    }
+    /**
+     * Creates a Inverted Unit with the provided name in this schema.
+     * @param name
+     */
+    async createInvertedUnit(name) {
+        return this.createItem(InvertedUnit, name);
+    }
+    createInvertedUnitSync(name) {
+        return this.createItem(InvertedUnit, name);
+    }
+    /**
+     * Creates an Format with the provided name in this schema.
+     * @param name
+     */
+    async createFormat(name) {
+        return this.createItem(Format, name);
+    }
+    createFormatSync(name) {
+        return this.createItem(Format, name);
+    }
+    /**
+     * Creates a UnitSystem with the provided name in this schema.
+     * @param name
+     */
+    async createUnitSystem(name) {
+        return this.createItem(UnitSystem, name);
+    }
+    createUnitSystemSync(name) {
+        return this.createItem(UnitSystem, name);
+    }
+    /**
+     * Creates a Phenomenon with the provided name in this schema.
+     * @param name
+     */
+    async createPhenomenon(name) {
+        return this.createItem(Phenomenon, name);
+    }
+    createPhenomenonSync(name) {
+        return this.createItem(Phenomenon, name);
+    }
+    /**
+     * Creates a Unit with the provided name in this schema.
+     * @param name
+     */
+    async createUnit(name) {
+        return this.createItem(Unit, name);
+    }
+    createUnitSync(name) {
+        return this.createItem(Unit, name);
+    }
+    /**
+     * Creates an PropertyCategory with the provided name in this schema.
+     * @param name
+     */
+    async createPropertyCategory(name) {
+        return this.createItem(PropertyCategory, name);
+    }
+    createPropertyCategorySync(name) {
+        return this.createItem(PropertyCategory, name);
+    }
+    /**
+     *
+     * @param refSchema
+     */
+    async addReference(refSchema) {
+        // TODO validation of reference schema. For now just adding
+        this.addReferenceSync(refSchema);
+    }
+    addReferenceSync(refSchema) {
+        this.references.push(refSchema);
+    }
+    /**
+     * @alpha Used for schema editing.
+     */
+    setContext(context) {
+        this._context = context;
+    }
+    /**
+     * Sets the version of the SchemaKey identifying the schema.
+     * @param readVersion The read version of the schema. If undefined, the value from the existing SchemaKey will be used.
+     * @param writeVersion The write version of the schema. If undefined, the value from the existing SchemaKey will be used.
+     * @param minorVersion The minor version of the schema. If undefined, the value from the existing SchemaKey will be used.
+     */
+    setVersion(readVersion, writeVersion, minorVersion) {
+        if (!this._schemaKey)
+            throw new ECObjectsError(ECObjectsStatus.InvalidSchemaKey, `The schema '${this.name}' has an invalid SchemaKey.`);
+        const newVersion = new ECVersion(readVersion ?? this._schemaKey.readVersion, writeVersion ?? this._schemaKey.writeVersion, minorVersion ?? this._schemaKey.minorVersion);
+        this._schemaKey = new SchemaKey(this._schemaKey.name, newVersion);
+    }
+    /**
+     * Gets an item from within this schema. To get by full name use lookupItem instead.
+     * @param key the local (unqualified) name, lookup is case-insensitive
+     */
+    async getItem(name) {
+        // this method exists so we can rewire it later when we load partial schemas, for now it is identical to the sync version
+        return this.getItemSync(name);
+    }
+    /**
+     * Gets an item from within this schema. To get by full name use lookupItem instead.
+     * @param key the local (unqualified) name, lookup is case-insensitive
+     */
+    getItemSync(name) {
+        // Case-insensitive search
+        return this._items.get(name.toUpperCase());
+    }
+    /**
+     * Attempts to find a schema item within this schema or a (directly) referenced schema
+     * @param key The full name or a SchemaItemKey identifying the desired item.
+     */
+    async lookupItem(key) {
+        let schemaName, itemName;
+        if (typeof (key) === "string") {
+            [schemaName, itemName] = SchemaItem.parseFullName(key);
+        }
+        else {
+            itemName = key.name;
+            schemaName = key.schemaName;
+        }
+        if (!schemaName || schemaName.toUpperCase() === this.name.toUpperCase()) {
+            return this.getItem(itemName);
+        }
+        const refSchema = await this.getReference(schemaName);
+        if (!refSchema)
+            return undefined;
+        return refSchema.getItem(itemName);
+    }
+    /**
+     * Attempts to find a schema item within this schema or a (directly) referenced schema
+     * @param key The full name or a SchemaItemKey identifying the desired item.
+     */
+    lookupItemSync(key) {
+        let schemaName, itemName;
+        if (typeof (key) === "string") {
+            [schemaName, itemName] = SchemaItem.parseFullName(key);
+        }
+        else {
+            itemName = key.name;
+            schemaName = key.schemaName;
+        }
+        if (!schemaName || schemaName.toUpperCase() === this.name.toUpperCase()) {
+            return this.getItemSync(itemName);
+        }
+        const refSchema = this.getReferenceSync(schemaName);
+        if (!refSchema)
+            return undefined;
+        return refSchema.getItemSync(itemName);
+    }
+    getItems() {
+        if (!this._items)
+            return new Map().values();
+        return this._items.values();
+    }
+    *getClasses() {
+        for (const [, value] of this._items) {
+            if (ECClass.isECClass(value))
+                yield value;
+        }
+    }
+    async getReference(refSchemaName) {
+        if (this.references.length === 0)
+            return undefined;
+        return this.references.find((ref) => ref.name.toLowerCase() === refSchemaName.toLowerCase());
+    }
+    getReferenceNameByAlias(alias) {
+        if (this.references.length === 0)
+            return undefined;
+        const schema = this.references.find((ref) => ref.alias ? ref.alias.toLowerCase() === alias.toLowerCase() : false);
+        return schema ? schema.name : undefined;
+    }
+    getReferenceSync(refSchemaName) {
+        if (this.references.length === 0)
+            return undefined;
+        return this.references.find((ref) => ref.name.toLowerCase() === refSchemaName.toLowerCase());
+    }
+    /**
+     * Save this Schema's properties to an object for serializing to JSON.
+     */
+    toJSON() {
+        const schemaJson = {};
+        schemaJson.$schema = SCHEMAURL3_2_JSON; // $schema is required
+        schemaJson.name = this.name; // name is required
+        schemaJson.version = this.schemaKey.version.toString(true);
+        schemaJson.alias = this.alias; // alias is required
+        if (undefined !== this.label) // label is optional
+            schemaJson.label = this.label;
+        if (undefined !== this.description) // description is optional
+            schemaJson.description = this.description;
+        if (undefined !== this.references && this.references.length > 0) // references is optional
+            schemaJson.references = this.references.map(({ name, schemaKey }) => ({ name, version: schemaKey.version.toString() }));
+        const customAttributes = serializeCustomAttributes(this.customAttributes);
+        if (undefined !== customAttributes)
+            schemaJson.customAttributes = customAttributes;
+        if (this._items.size > 0) {
+            schemaJson.items = {};
+            this._items.forEach((schemaItem) => {
+                schemaJson.items[schemaItem.name] = schemaItem.toJSON(false, true);
+            });
+        }
+        return schemaJson;
+    }
+    /**
+     * Converts the schema to a DOM XML Document.
+     * @param schemaXml An empty DOM document to which the schema will be written
+     */
+    async toXml(schemaXml) {
+        const schemaMetadata = schemaXml.createElement("ECSchema");
+        schemaMetadata.setAttribute("xmlns", SCHEMAURL3_2_XML);
+        schemaMetadata.setAttribute("version", this.schemaKey.version.toString());
+        schemaMetadata.setAttribute("schemaName", this.name);
+        schemaMetadata.setAttribute("alias", this.alias ? this.alias : "");
+        if (undefined !== this.label)
+            schemaMetadata.setAttribute("displayLabel", this.label);
+        if (undefined !== this.description)
+            schemaMetadata.setAttribute("description", this.description);
+        // Map used for CA serialization
+        const refSchemaMap = new Map();
+        this.references.forEach(({ name, schemaKey, alias }) => {
+            const schemaRef = schemaXml.createElement("ECSchemaReference");
+            schemaRef.setAttribute("name", name);
+            schemaRef.setAttribute("version", schemaKey.version.toString());
+            schemaRef.setAttribute("alias", alias ? alias : "");
+            schemaMetadata.appendChild(schemaRef);
+            refSchemaMap.set(name, schemaKey.version.toString());
+        });
+        if (this._customAttributes) {
+            const parentElem = schemaXml.createElement("ECCustomAttributes");
+            for (const [name, attribute] of this._customAttributes) {
+                const caElem = await XmlSerializationUtils.writeCustomAttribute(name, attribute, schemaXml, this);
+                parentElem.appendChild(caElem);
+            }
+            schemaMetadata.appendChild(parentElem);
+        }
+        for (const [, item] of this._items) {
+            const itemXml = await item.toXml(schemaXml);
+            schemaMetadata.appendChild(itemXml);
+        }
+        schemaXml.appendChild(schemaMetadata);
+        return schemaXml;
+    }
+    /**
+     * Loads the schema header (name, version alias, label and description) from the input SchemaProps
+     */
+    fromJSONSync(schemaProps) {
+        if (undefined === this._schemaKey) {
+            const schemaName = schemaProps.name;
+            const version = ECVersion.fromString(schemaProps.version);
+            this._schemaKey = new SchemaKey(schemaName, version);
+        }
+        else {
+            if (schemaProps.name.toLowerCase() !== this.name.toLowerCase())
+                throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The Schema ${this.name} does not match the provided name, '${schemaProps.name}'.`);
+            if (this.schemaKey.version.compare(ECVersion.fromString(schemaProps.version)))
+                throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The Schema ${this.name} has the version '${this.schemaKey.version}' that does not match the provided version '${schemaProps.version}'.`);
+        }
+        if (SCHEMAURL3_2_JSON !== schemaProps.$schema && SCHEMAURL3_2_XML !== schemaProps.$schema) // TODO: Allow for 3.x URI versions to allow the API to read newer specs. (Start at 3.2 though)
+            throw new ECObjectsError(ECObjectsStatus.MissingSchemaUrl, `The Schema ${this.name} has an unsupported namespace '${schemaProps.$schema}'.`);
+        if (ECName.validate(schemaProps.alias)) {
+            this._alias = schemaProps.alias;
+        }
+        else {
+            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The Schema ${schemaProps.name} does not have the required 'alias' attribute.`);
+        }
+        if (undefined !== schemaProps.label)
+            this._label = schemaProps.label;
+        if (undefined !== schemaProps.description)
+            this._description = schemaProps.description;
+    }
+    /**
+     * Loads the schema header (name, version alias, label and description) from the input SchemaProps
+     */
+    async fromJSON(schemaProps) {
+        this.fromJSONSync(schemaProps);
+    }
+    /**
+     * Completely loads the SchemaInfo from the input json and starts loading the entire schema.  The complete schema can be retrieved from the
+     * schema context using the getCachedSchema method
+     */
+    static async startLoadingFromJson(jsonObj, context) {
+        const schema = new Schema(context);
+        const reader = new SchemaReadHelper(JsonParser, context);
+        const rawSchema = typeof jsonObj === "string" ? JSON.parse(jsonObj) : jsonObj;
+        return reader.readSchemaInfo(schema, rawSchema);
+    }
+    static async fromJson(jsonObj, context) {
+        let schema = new Schema(context);
+        const reader = new SchemaReadHelper(JsonParser, context);
+        const rawSchema = typeof jsonObj === "string" ? JSON.parse(jsonObj) : jsonObj;
+        schema = await reader.readSchema(schema, rawSchema);
+        return schema;
+    }
+    /**
+     * Completely loads the Schema from the input json. The schema is cached in the schema context.
+     */
+    static fromJsonSync(jsonObj, context) {
+        let schema = new Schema(context);
+        const reader = new SchemaReadHelper(JsonParser, context);
+        const rawSchema = typeof jsonObj === "string" ? JSON.parse(jsonObj) : jsonObj;
+        schema = reader.readSchemaSync(schema, rawSchema);
+        return schema;
+    }
+    /**
+     * @internal
+     */
+    static isSchema(object) {
+        const schema = object;
+        return schema !== undefined && schema.schemaKey !== undefined && schema.context !== undefined;
+    }
+    /**
+     * @alpha
+     * Used for schema editing.
+     */
+    setDisplayLabel(displayLabel) {
+        this._label = displayLabel;
+    }
+    /**
+     * @alpha
+     * Used for schema editing.
+     */
+    setDescription(description) {
+        this._description = description;
+    }
+}
+/**
+ * Hackish approach that works like a "friend class" so we can access protected members without making them public.
+ * We cannot put this into Helper.ts and make it non-export, because we are importing Helper.ts from this file, and the circular import
+ * would prevent this class from extending Schema.
+ * @internal
+ */
+export class MutableSchema extends Schema {
+}
+//# sourceMappingURL=Schema.js.map