@itwin/ecschema-metadata 5.0.0-dev.98 → 5.0.0

package/lib/esm/Metadata/Schema.js

@@ -10,7 +10,7 @@ import { JsonParser } from "../Deserialization/JsonParser";
 import { XmlParser } from "../Deserialization/XmlParser";
 import { XmlSerializationUtils } from "../Deserialization/XmlSerializationUtils";
 import { isSupportedSchemaItemType } from "../ECObjects";
-import { ECObjectsError, ECObjectsStatus } from "../Exception";
+import { ECSchemaError, ECSchemaStatus } from "../Exception";
 import { ECVersion, SchemaItemKey, SchemaKey } from "../SchemaKey";
 import { ECName } from "../ECName";
 import { ECClass, StructClass } from "./Class";
@@ -31,7 +31,7 @@ import { Unit } from "./Unit";
 import { UnitSystem } from "./UnitSystem";
 import { ECSchemaNamespaceUris } from "../Constants";
 /**
- * @beta
+ * @public @preview
  */
 export class Schema {
     static _currentECSpecVersion = "3.2";
@@ -55,34 +55,34 @@ export class Schema {
             this._alias = alias;
         }
         else if (nameOrKey !== undefined) {
-            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The Schema ${this.name} does not have the required 'alias' attribute.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The Schema ${this.name} does not have the required 'alias' attribute.`);
         }
         this._originalECSpecMajorVersion = Schema.currentECSpecMajorVersion;
         this._originalECSpecMinorVersion = Schema.currentECSpecMinorVersion;
     }
     get schemaKey() {
         if (undefined === this._schemaKey)
-            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
         return this._schemaKey;
     }
     get name() {
         if (this._schemaKey === undefined)
-            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
         return this.schemaKey.name;
     }
     get readVersion() {
         if (this._schemaKey === undefined)
-            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
         return this.schemaKey.readVersion;
     }
     get writeVersion() {
         if (this._schemaKey === undefined)
-            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
         return this.schemaKey.writeVersion;
     }
     get minorVersion() {
         if (this._schemaKey === undefined)
-            throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The schema has an invalid or missing SchemaKey.`);
         return this.schemaKey.minorVersion;
     }
     get originalECSpecMajorVersion() { return this._originalECSpecMajorVersion; }
@@ -95,7 +95,7 @@ export class Schema {
     }
     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.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The Schema ${this.name} does not have the required 'alias' attribute.`);
         }
         else {
             return this._alias;
@@ -120,18 +120,19 @@ export class Schema {
         if (this.name !== schemaName) {
             const newSchemaRef = this.getReferenceSync(schemaName);
             if (undefined === newSchemaRef)
-                throw new ECObjectsError(ECObjectsStatus.InvalidECJson, `Unable to find the referenced SchemaItem ${itemName}.`);
+                throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `Unable to find the referenced SchemaItem ${itemName}.`);
             schemaKey = newSchemaRef.schemaKey;
         }
         return new SchemaItemKey(itemName, schemaKey);
     }
+    /** @internal */
     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`);
+            throw new ECSchemaError(ECSchemaStatus.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
+     * @internal
      */
     createClass(type, name, modifier) {
         const item = new type(this, name, modifier);
@@ -141,7 +142,7 @@ export class Schema {
     /**
      * Deletes a class from within this schema.
      * @param name the local (unqualified) class name, lookup is case-insensitive
-     * @alpha
+     * @internal
      */
     async deleteClass(name) {
         const schemaItem = await this.getItem(name);
@@ -152,7 +153,7 @@ export class Schema {
     /**
      * Deletes a class from within this schema.
      * @param name the local (unqualified) class name, lookup is case-insensitive
-     * @alpha
+     * @internal
      */
     deleteClassSync(name) {
         const schemaItem = this.getItemSync(name);
@@ -162,7 +163,7 @@ export class Schema {
     /**
      * Deletes a SchemaItem from within this schema.
      * @param name the local (unqualified) class name, lookup is case-insensitive
-     * @alpha
+     * @internal
      */
     async deleteSchemaItem(name) {
         const schemaItem = await this.getItem(name);
@@ -173,21 +174,20 @@ export class Schema {
     /**
      * Deletes a SchemaItem from within this schema.
      * @param name the local (unqualified) class name, lookup is case-insensitive
-     * @alpha
+     * @internal
      */
     deleteSchemaItemSync(name) {
         const schemaItem = this.getItemSync(name);
         if (SchemaItem.isSchemaItem(schemaItem))
             this._items.delete(name.toUpperCase());
     }
-    /**
-     * @alpha
-     */
+    /** @internal */
     createItem(type, name) {
         const item = new type(this, name);
         this.addItem(item);
         return item;
     }
+    /** @internal */
     addCustomAttribute(customAttribute) {
         if (!this._customAttributes)
             this._customAttributes = new Map();
@@ -197,27 +197,33 @@ export class Schema {
      * Creates a EntityClass with the provided name in this schema.
      * @param name
      * @param modifier
+     * @internal
      */
     async createEntityClass(name, modifier) {
         return this.createClass(EntityClass, name, modifier);
     }
+    /** @internal */
     createEntityClassSync(name, modifier) {
         return this.createClass(EntityClass, name, modifier);
     }
     /**
      * Creates a Mixin with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createMixinClass(name) { return this.createClass(Mixin, name); }
+    /** @internal */
     createMixinClassSync(name) { return this.createClass(Mixin, name); }
     /**
      * Creates a StructClass with the provided name in this schema.
      * @param name
      * @param modifier
+     * @internal
      */
     async createStructClass(name, modifier) {
         return this.createClass(StructClass, name, modifier);
     }
+    /** @internal */
     createStructClassSync(name, modifier) {
         return this.createClass(StructClass, name, modifier);
     }
@@ -225,10 +231,12 @@ export class Schema {
      * Creates a CustomAttributeClass with the provided name in this schema.
      * @param name
      * @param modifier
+     * @internal
      */
     async createCustomAttributeClass(name, modifier) {
         return this.createClass(CustomAttributeClass, name, modifier);
     }
+    /** @internal */
     createCustomAttributeClassSync(name, modifier) {
         return this.createClass(CustomAttributeClass, name, modifier);
     }
@@ -236,20 +244,26 @@ export class Schema {
      * Creates a RelationshipClass with the provided name in this schema.
      * @param name
      * @param modifier
+     * @internal
      */
     async createRelationshipClass(name, modifier) {
         return this.createRelationshipClassSync(name, modifier);
     }
+    /** @internal */
     createRelationshipClassSync(name, modifier) {
         return this.createClass(RelationshipClass, name, modifier);
     }
     /**
      * Creates an Enumeration with the provided name in this schema.
      * @param name
+     * @param primitiveType
+     *
+     * @internal
      */
     async createEnumeration(name, primitiveType) {
         return this.createEnumerationSync(name, primitiveType);
     }
+    /** @internal */
     createEnumerationSync(name, primitiveType) {
         const item = new Enumeration(this, name, primitiveType);
         this.addItem(item);
@@ -258,97 +272,113 @@ export class Schema {
     /**
      * Creates an KindOfQuantity with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createKindOfQuantity(name) {
         return this.createKindOfQuantitySync(name);
     }
+    /** @internal */
     createKindOfQuantitySync(name) {
         return this.createItem(KindOfQuantity, name);
     }
     /**
      * Creates a Constant with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createConstant(name) {
         return this.createItem(Constant, name);
     }
+    /** @internal */
     createConstantSync(name) {
         return this.createItem(Constant, name);
     }
     /**
      * Creates a Inverted Unit with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createInvertedUnit(name) {
         return this.createItem(InvertedUnit, name);
     }
+    /** @internal */
     createInvertedUnitSync(name) {
         return this.createItem(InvertedUnit, name);
     }
     /**
      * Creates an Format with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createFormat(name) {
         return this.createItem(Format, name);
     }
+    /** @internal */
     createFormatSync(name) {
         return this.createItem(Format, name);
     }
     /**
      * Creates a UnitSystem with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createUnitSystem(name) {
         return this.createItem(UnitSystem, name);
     }
+    /** @internal */
     createUnitSystemSync(name) {
         return this.createItem(UnitSystem, name);
     }
     /**
      * Creates a Phenomenon with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createPhenomenon(name) {
         return this.createItem(Phenomenon, name);
     }
+    /** @internal */
     createPhenomenonSync(name) {
         return this.createItem(Phenomenon, name);
     }
     /**
      * Creates a Unit with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createUnit(name) {
         return this.createItem(Unit, name);
     }
+    /** @internal */
     createUnitSync(name) {
         return this.createItem(Unit, name);
     }
     /**
      * Creates an PropertyCategory with the provided name in this schema.
      * @param name
+     * @internal
      */
     async createPropertyCategory(name) {
         return this.createItem(PropertyCategory, name);
     }
+    /** @internal */
     createPropertyCategorySync(name) {
         return this.createItem(PropertyCategory, name);
     }
     /**
      *
      * @param refSchema
+     * @internal
      */
     async addReference(refSchema) {
         // TODO validation of reference schema. For now just adding
         this.addReferenceSync(refSchema);
     }
+    /** @internal */
     addReferenceSync(refSchema) {
         this.references.push(refSchema);
     }
-    /**
-     * @alpha Used for schema editing.
-     */
+    /** @internal */
     setContext(context) {
         this._context = context;
     }
@@ -357,10 +387,11 @@ export class 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.
+     * @internal
      */
     setVersion(readVersion, writeVersion, minorVersion) {
         if (!this._schemaKey)
-            throw new ECObjectsError(ECObjectsStatus.InvalidSchemaKey, `The schema '${this.name}' has an invalid SchemaKey.`);
+            throw new ECSchemaError(ECSchemaStatus.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);
     }
@@ -545,7 +576,7 @@ export class Schema {
      */
     toJSON() {
         if (this._isECSpecVersionUnsupported)
-            throw new ECObjectsError(ECObjectsStatus.NewerECSpecVersion, `The Schema '${this.name}' has an unsupported ECSpecVersion and cannot be serialized.`);
+            throw new ECSchemaError(ECSchemaStatus.NewerECSpecVersion, `The Schema '${this.name}' has an unsupported ECSpecVersion and cannot be serialized.`);
         const schemaJson = {};
         schemaJson.$schema = ECSchemaNamespaceUris.SCHEMAURL3_2_JSON; // $schema is required
         schemaJson.name = this.name; // name is required
@@ -574,7 +605,7 @@ export class Schema {
      */
     async toXml(schemaXml) {
         if (this._isECSpecVersionUnsupported)
-            throw new ECObjectsError(ECObjectsStatus.NewerECSpecVersion, `The Schema '${this.name}' has an unsupported ECSpecVersion and cannot be serialized.`);
+            throw new ECSchemaError(ECSchemaStatus.NewerECSpecVersion, `The Schema '${this.name}' has an unsupported ECSpecVersion and cannot be serialized.`);
         const schemaMetadata = schemaXml.createElement("ECSchema");
         schemaMetadata.setAttribute("xmlns", ECSchemaNamespaceUris.SCHEMAURL3_2_XML);
         schemaMetadata.setAttribute("version", this.schemaKey.version.toString());
@@ -620,12 +651,12 @@ export class Schema {
         }
         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}'.`);
+                throw new ECSchemaError(ECSchemaStatus.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}'.`);
+                throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The Schema ${this.name} has the version '${this.schemaKey.version}' that does not match the provided version '${schemaProps.version}'.`);
         }
         if (schemaProps.$schema.match(`https://dev\\.bentley\\.com/json_schemas/ec/([0-9]+)/ecschema`) == null && schemaProps.$schema.match(`http://www\\.bentley\\.com/schemas/Bentley\\.ECXML\\.([0-9]+)`) == null)
-            throw new ECObjectsError(ECObjectsStatus.MissingSchemaUrl, `The Schema '${this.name}' has an unsupported namespace '${schemaProps.$schema}'.`);
+            throw new ECSchemaError(ECSchemaStatus.MissingSchemaUrl, `The Schema '${this.name}' has an unsupported namespace '${schemaProps.$schema}'.`);
         // The schema props have not been parsed. Parse the ECXml version from the $schema attribute
         let ecVersion;
         if (schemaProps.ecSpecMajorVersion === undefined || schemaProps.ecSpecMinorVersion === undefined) {
@@ -637,12 +668,12 @@ export class Schema {
         this._originalECSpecMajorVersion = ecVersion.readVersion;
         this._originalECSpecMinorVersion = ecVersion.writeVersion;
         if (ecVersion.readVersion !== 3 || (ecVersion.readVersion === 3 && ecVersion.writeVersion < 2))
-            throw new ECObjectsError(ECObjectsStatus.InvalidECVersion, `The Schema '${this.name}' has an unsupported ECVersion ${ecVersion.readVersion}.${ecVersion.writeVersion} and cannot be loaded.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECVersion, `The Schema '${this.name}' has an unsupported ECVersion ${ecVersion.readVersion}.${ecVersion.writeVersion} and cannot be loaded.`);
         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.`);
+            throw new ECSchemaError(ECSchemaStatus.InvalidECJson, `The Schema ${schemaProps.name} does not have the required 'alias' attribute.`);
         }
         if (undefined !== schemaProps.label)
             this._label = schemaProps.label;
@@ -689,27 +720,18 @@ export class Schema {
         const schema = object;
         return schema !== undefined && schema.schemaKey !== undefined && schema.context !== undefined;
     }
-    /**
-     * @alpha
-     * Used for schema editing.
-     */
+    /** @internal */
     setDisplayLabel(displayLabel) {
         this._label = displayLabel;
     }
-    /**
-     * @alpha
-     * Used for schema editing.
-     */
+    /** @internal */
     setDescription(description) {
         this._description = description;
     }
-    /**
-     * @alpha
-     * Used for schema editing.
-     */
+    /** @internal */
     setAlias(alias) {
         if (!ECName.validate(alias)) {
-            throw new ECObjectsError(ECObjectsStatus.InvalidECName, "The specified schema alias is invalid.");
+            throw new ECSchemaError(ECSchemaStatus.InvalidECName, "The specified schema alias is invalid.");
         }
         this._alias = alias;
     }