In a previous chapter, we created a feature schema and added a feature class to it. The feature class had three properties: an integer data property, a string data property, and a geometric property. We applied this feature schema to the data store. We are now ready to create feature data objects, which are instances of the feature class, and insert them into the data store.
We can now create feature data objects, which are instances of the feature class, by defining a set of property values corresponding to the properties defined for the class and then inserting them into the data store.
An FDO class correspondends roughly to a table definition in a relational database and a property of a class corresponds roughly to a column definition in a table. Adding the property values corresponds roughly to adding a row in the table.
The main distinction between a data value or geometry value and a property value is the order in which they are created. A data value or geometry value object is created first and is then used to create a property value object. The property value object is then added to the value collection object belonging to the Insert command object. Then, the command is executed.
An insert operation consists of the following steps:
- Create the insert command object (type FdoIInsert); this object can be reused for multiple insert operations.
- Point the insert command object at the feature class to which you are adding values (call the SetFeatureClassName(<className>) method).
- From the insert command object, obtain a pointer using the GetPropertyValues() method to a value collection object (type FdoPropertyValueCollection). You will add property values to the insert command object by adding values to the collection object.
- Create a data value (type FdoDataValue) or geometry value (type FdoGeometryValue) object. Creating the data value is straightforward; you pass the string or integer value to a static Create() method. Creating the geometry value is described in Geometry Property Values.
- Create a property value (type FdoPropertyValue) object, which involves passing the data value or geometry value object as an argument to a static Create() method.
- Add the property value object to the value collection object.
- Execute the Insert command.
A data value object contains data whose type is one of the following:
- Boolean
- Byte
- DateTime
- Decimal
- Double
- Int16
- Int32
- Int64
- Single (another floating point type)
- String
- Binary large object (BLOB)
- Character large object (CLOB)
The data value object is added to the data property value object. The data property value object is added to the property value collection belonging to the Insert command.
A geometry property value object contains a geometry in the form of a byte array. A geometry can be relatively simple, for example, a point (a single pair of ordinates), or quite complex, for example, a polygon (one or more arrays of ordinates). In the latter case, a number of geometry objects are created and then combined together to form the target geometry. Finally, the target geometry is converted to a byte array and incorporated into the geometry property value object.
Creating a geometry value object consists of the following steps:
- Create a geometry value object (type FdoGeometryValue) using a static Create() method.
- Create a geometry factory object (type FdoAgfGeometryFactory) using a static GetInstance() method. This object is used to create the geometry object or objects which comprise the target geometry.
- Create the required geometry object or objects using the appropriate Create<geometry> method() belonging to the geometry factory object.
- Use the geometry factory object to convert the target geometry object to a byte array.
- Incorporate the byte array into the geometry property value object.
Example: Inserting an Integer, a String, and a Geometry Value
The following sample code shows how to insert an integer, a string, and a geometry value:
// create the insert command
FdoPtr<FdoIInsert> sampleInsert;
sampleInsert = (FdoIInsert *)
connection->CreateCommand(FdoCommandType_Insert);
// index returned by the operation which adds a value to the value
// collection
FdoInt32 valueCollectionIndex = 0;
// point the Insert command to the target class
// use a fully qualified class name
// whose format is <schemaName>:<className>
sampleInsert-> SetFeatureClassName(L"SampleFeatureSchema:SampleFeatureClass");
// get the pointer to the value collection used to add properties
// to the Insert command
FdoPtr<FdoPropertyValueCollection> samplePropertyValues;
samplePropertyValues = sampleInsert->GetPropertyValues();
// create an FdoDataValue for the identity property value
FdoPtr<FdoDataValue> sampleIdentityDataValue;
sampleIdentityDataValue = FdoDataValue::Create(101);
// add the FdoDataValue to the identity property value
FdoPtr<FdoPropertyValue> sampleIdentityPropertyValue;
sampleIdentityPropertyValue =
FdoPropertyValue::Create(L"SampleIdentityDataProperty",
sampleIdentityDataValue);
// add the identity property value to the value collection
valueCollectionIndex =
samplePropertyValues->Add(sampleIdentityPropertyValue);
// create an FdoDataValue for the name property value
FdoPtr<FdoDataValue> sampleNameDataValue;
sampleNameDataValue = FdoDataValue::Create(L"Blue Lake");
// add the FdoDataValue to the name property value
FdoPtr<FdoPropertyValue> sampleNamePropertyValue;
sampleNamePropertyValue =
FdoPropertyValue::Create(L"SampleNameDataProperty",
sampleNameDataValue);
// add the name property value to the value collection
valueCollectionIndex =
samplePropertyValues->Add(sampleNamePropertyValue);
// create an FdoGeometryValue for the geometry property value
// this polygon represents a lake which has an island
// the outer shoreline of the lake is defined as a linear ring
// the shoreline of the island is defined as a linear ring
// the outer shoreline is the external boundary of the polygon
// the island shoreline is an internal linear ring
// a polygon geometry can have zero or more internal rings
FdoPtr<FdoGeometryValue> sampleGeometryValue;
sampleGeometryValue = FdoGeometryValue::Create();
// create an instance of a geometry factory used to create the
// geometry objects
FdoPtr<FdoFgfGeometryFactory> sampleGeometryFactory;
sampleGeometryFactory = FdoFgfGeometryFactory::GetInstance();
// define the external boundary of the polygon, the shoreline of
// Blue Lake
FdoPtr<FdoILinearRing> exteriorRingBlueLake;
FdoInt32 numBlueLakeShorelineOrdinates = 10;
double blueLakeExteriorRingOrdinates[] = {52.0, 18.0, 66.0, 23.0,
73.0, 9.0, 48.0, 6.0, 52.0, 18.0};
exteriorRingBlueLake = sampleGeometryFactory->CreateLinearRing(
FdoDimensionality_XY, numBlueLakeShorelineOrdinates,
blueLakeExteriorRingOrdinates);
// define the shoreline of Goose Island which is on Blue Lake
// this is the sole member of the list of interior rings
FdoPtr<FdoILinearRing> linearRingGooseIsland;
FdoInt32 numGooseIslandShorelineOrdinates = 10;
double gooseIslandLinearRingOrdinates[] = {59.0, 18.0, 67.0, 18.0,
67.0, 13.0, 59.0, 13.0, 59.0, 18.0};
linearRingGooseIsland = sampleGeometryFactory->CreateLinearRing(
FdoDimensionality_XY, numGooseIslandShorelineOrdinates,
gooseIslandLinearRingOrdinates);
// add the Goose Island linear ring to the list of interior rings
FdoPtr<FdoLinearRingCollection> interiorRingsBlueLake;
interiorRingsBlueLake = FdoLinearRingCollection::Create();
interiorRingsBlueLake->Add(linearRingGooseIsland);
// create the Blue Lake polygon
FdoPtr<FdoIPolygon> blueLake;
blueLake =
sampleGeometryFactory->CreatePolygon(exteriorRingBlueLake,
interiorRingsBlueLake);
// convert the Blue Lake polygon into a byte array
// and set the geometry value to this byte array
FdoByteArray * geometryByteArray =
sampleGeometryFactory->GetAgf(blueLake);
sampleGeometryValue->SetGeometry(geometryByteArray);
// add the Blue Lake FdoGeometryValue to the geometry property value
FdoPtr<FdoPropertyValue> sampleGeometryPropertyValue;
sampleGeometryPropertyValue =
FdoPropertyValue::Create(L"SampleGeometryProperty",
sampleGeometryValue);
// add the geometry property value to the value collection
valueCollectionIndex =
samplePropertyValues->Add(sampleGeometryPropertyValue);
// do the insertion
// the command returns an FdoIFeatureReader
FdoPtr<FdoIFeatureReader sampleFeatureReader;
sampleFeatureReader = sampleInsert->Execute();