Depict null values in array type ECProperty output

core/backend/src/test/element/NullStructArray.test.ts → core/backend/src/test/element/NullBehaviors.test.ts

@@ -4,21 +4,24 @@
 *--------------------------------------------------------------------------------------------*/
 import { assert, expect } from "chai";
 import { Id64, Id64String } from "@itwin/core-bentley";
-import {
-  BriefcaseIdValue, Code,  ColorDef,  GeometricElementProps, IModel,
-  SubCategoryAppearance,
-} from "@itwin/core-common";
-import {   _nativeDb, IModelDb, IModelJsFs, SnapshotDb, SpatialCategory } from "../../core-backend";
+import { Code, ColorDef, GeometricElementProps, IModel, SubCategoryAppearance } from "@itwin/core-common";
+import { IModelDb, IModelJsFs, SnapshotDb, SpatialCategory } from "../../core-backend";
 import { IModelTestUtils } from "../IModelTestUtils";
 
+interface TestSchemaLocation {
+  city: string;
+  zip: number;
+}
+
 interface TestElement extends GeometricElementProps {
-  addresses: [null, {city: "Pune", zip: 28}];
+  addresses: TestSchemaLocation[];
+  favoriteNumbers: number[];
 }
 
 function initElemProps( _iModelName: IModelDb, modId: Id64String, catId: Id64String, autoHandledProp: any): GeometricElementProps {
   // Create props
   const elementProps: GeometricElementProps = {
-    classFullName: "Test:Foo",
+    classFullName: "Test:TestClass",
     model: modId,
     category: catId,
     code: Code.createEmpty(),
@@ -28,36 +31,33 @@ function initElemProps( _iModelName: IModelDb, modId: Id64String, catId: Id64Str
   return elementProps;
 }
 
-describe("Insert Null elements in Struct Array, and ensure they are returned while querying rows", () => {
+describe("Various ECProperties null behavior handling cases test fixture", () => {
   const testSchema = `<?xml version="1.0" encoding="UTF-8"?>
-  <ECSchema schemaName="Test" alias="test" version="01.00.00" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.1">
-  <ECSchemaReference name="BisCore" version="01.00.04" alias="bis"/>
-  <ECStructClass typeName="Location" modifier="Sealed">
-    <ECProperty propertyName="City" typeName="string"/>
-    <ECProperty propertyName="Zip" typeName="int"/>
-  </ECStructClass>
-  <ECEntityClass typeName="Foo" modifier="Sealed">
-  <BaseClass>bis:PhysicalElement</BaseClass>
-    <ECArrayProperty propertyName="I_Array" typeName="int"/>
-    <ECArrayProperty propertyName="Dt_Array" typeName="dateTime"/>
-    <ECStructArrayProperty propertyName="Addresses" typeName="Location"/>
-  </ECEntityClass>
+  <ECSchema schemaName="TestSchema" alias="test" version="01.00.00" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.1">
+    <ECSchemaReference name="BisCore" version="01.00.04" alias="bis"/>
+    <ECStructClass typeName="Location" modifier="None">
+      <ECProperty propertyName="City" typeName="string"/>
+      <ECProperty propertyName="Zip" typeName="int"/>
+    </ECStructClass>
+    <ECEntityClass typeName="TestClass" modifier="None">
+      <BaseClass>bis:PhysicalElement</BaseClass>
+      <ECArrayProperty propertyName="FavoriteNumbers" typeName="int"/>
+      <ECStructArrayProperty propertyName="Addresses" typeName="Location"/>
+    </ECEntityClass>
   </ECSchema>`;
 
-  const schemaFileName = "NullStructElementTest.01.00.00.xml";
-  const iModelFileName = "NullStructElementTest.bim";
-  const categoryName = "NullStructElement";
-  const subDirName = "NullStructElement";
+  const schemaFileName = "NullBehaviorsTest.01.00.00.xml";
+  const iModelFileName = "NullBehaviorsTest.bim";
+  const subDirName = "NullBehaviors";
   const iModelPath = IModelTestUtils.prepareOutputFile(subDirName, iModelFileName);
+  const categoryName = "NullBehaviorsCategory";
 
   before(async () => {
-    // write schema to disk as we do not have api to import xml directly
     const testSchemaPath = IModelTestUtils.prepareOutputFile(subDirName, schemaFileName);
     IModelJsFs.writeFileSync(testSchemaPath, testSchema);
 
-    const imodel = SnapshotDb.createEmpty(iModelPath, { rootSubject: { name: "InsertNullStructArrayTest" } });
+    const imodel = SnapshotDb.createEmpty(iModelPath, { rootSubject: { name: "NullBehaviorsTest" } });
     await imodel.importSchemas([testSchemaPath]);
-    imodel[_nativeDb].resetBriefcaseId(BriefcaseIdValue.Unassigned);
     IModelTestUtils.createAndInsertPhysicalPartitionAndModel(imodel, Code.createEmpty(), true);
 
     let spatialCategoryId = SpatialCategory.queryCategoryIdByName(imodel, IModel.dictionaryId, categoryName);
@@ -69,29 +69,30 @@ describe("Insert Null elements in Struct Array, and ensure they are returned whi
     imodel.close();
   });
 
-  it("Test for struct array to contain null structs", async () => {
-    const testFileName = IModelTestUtils.prepareOutputFile(subDirName, "roundtrip_correct_data.bim");
+  it("validates arrays to contain null values", async () => {
+    const testFileName = IModelTestUtils.prepareOutputFile(subDirName, "struct_array_contain_nulls.bim");
     const imodel = IModelTestUtils.createSnapshotFromSeed(testFileName, iModelPath);
-    const spatialCategoryId = SpatialCategory.queryCategoryIdByName(imodel, IModel.dictionaryId, categoryName);
+    const spatialCategoryId = SpatialCategory.queryCategoryIdByName(imodel, IModel.dictionaryId, categoryName)!;
     const [, newModelId] = IModelTestUtils.createAndInsertPhysicalPartitionAndModel(imodel, Code.createEmpty(), true);
 
-    // create element with auto handled properties
-    const expectedValue = initElemProps( imodel, newModelId, spatialCategoryId!, {
-      addresses: [null, {city: "Pune", zip: 28}],
+    const expectedProps = initElemProps(imodel, newModelId, spatialCategoryId, {
+      addresses: [null, { city: "Pune", zip: 28 }],
+      favoriteNumbers: [1, 44, 31, null, 81, 19],
     }) as TestElement;
 
-    // insert a element
-    const geomElement = imodel.elements.createElement(expectedValue);
+    // Insert an element containing a struct array with at least one null value
+    const geomElement = imodel.elements.createElement(expectedProps);
     const id = imodel.elements.insertElement(geomElement.toJSON());
     assert.isTrue(Id64.isValidId64(id), "insert worked");
     imodel.saveChanges();
 
-    // verify inserted element properties
+    // Verify the properties of the inserted element
     const actualValue = imodel.elements.getElementProps<TestElement>(id);
     expect(actualValue.addresses.length).to.equal(2);
-    expect(actualValue.addresses[0]).to.be.empty;
+    expect(actualValue.addresses).to.deep.equal([undefined, { city: "Pune", zip: 28 }]);
+    expect(actualValue.favoriteNumbers.length).to.equal(6);
+    expect(actualValue.favoriteNumbers).to.deep.equal([1, 44, 31, undefined, 81, 19]);
 
     imodel.close();
   });
-
 });

docs/learning/ECSQLNullBehaviors.md

@@ -12,6 +12,7 @@ Documentation schema sample:
   <ECSchemaReference name="CoreCustomAttributes" version="01.00.03" alias="CoreCA"/>
   <ECEntityClass typeName="DocsElement" modifier="None">
     <ECProperty propertyName="intProp" typeName="int"/>
+    <ECProperty propertyName="p2dProp" typeName="point2d"/>
     <ECArrayProperty propertyName="arrBoolProp" typeName="boolean" minOccurs="0" maxOccurs="unbounded"/>
     <ECStructProperty propertyName="structProp" typeName="StructType"/>
     <ECStructArrayProperty propertyName="arrStructProp" typeName="StructType" minOccurs="0" maxOccurs="unbounded"/>
@@ -27,7 +28,11 @@ Attempting to update any of the properties (`intProp`, `arrBoolProp`, `structPro
 
 ## Setting some complex property children to null
 
-To be added
+This section would cover partially setting a complex property (point2d, struct, array) to null.
+
+- A `point2d` type property must always have all its coordinates present, hence updating a point2d to be partially null is not a valid input and would result in the property not being updated. This is why updating `p2dProp` to `{ x: null, y: 2.5 }` would be invalid and take no effect on the element's property.
+- A `struct` type property can have all of their children properties set to null. The child property would end up being cleared from the parent object with the remaining properties remaining intact. This means that if `structProp` would include `{ doubleProp: 41.0, stringProp: null }`, the string property would be cleared with the doubleProp successfully updated to the expected value.
+- An `array` type (primitive or struct) property can store null values as any other value of the respective type. It would happen to be represented alongside the ordinary properties as null. E.g. updating `arrBoolProp` to `[false, true, null, false]` is a perfectly valid data entry for a boolean type array property.
 
 ## Setting all complex property children to null or making it empty