Skip to content

MultipleShapeFileFeatureSource

Namespace: ThinkGeo.Core

This class represents a FeatureSource backed by multiple ESRI Shape Files.

public class MultipleShapeFileFeatureSource : FeatureSource

Inheritance ObjectFeatureSourceMultipleShapeFileFeatureSource

Remarks:

None

Properties

ShapeFiles

public Collection<string> ShapeFiles { get; }

Property Value

Collection<String>

Indexes

public Collection<string> Indexes { get; }

Property Value

Collection<String>

MultipleShapeFilePattern

This parameter gets and sets the shape file pattern.

public string MultipleShapeFilePattern { get; set; }

Property Value

String
This parameter gets and sets the shape file pattern.

Remarks:

None.

IndexFilePattern

This parameter gets and sets the index file pattern.

public string IndexFilePattern { get; set; }

Property Value

String
This parameter gets and sets the index file pattern.

Remarks:

None.

Encoding

This property get and set the encoding information for the dbf.

public Encoding Encoding { get; set; }

Property Value

Encoding

IsEditable

This property returns if the FeatureSource allows edits or is read only.

public bool IsEditable { get; }

Property Value

Boolean

Remarks:

This property is useful to check if a specific FeatureSource accepts editing. If you call the BeginTransaction and this property is false then an exception will be raised.

For developers who are creating or extending a FeatureSource it is expected that you override this virtual method if the new FeatureSource you are creating allows edits. By default the decimalDegreesValue if false meaning that if you want to allow edits you must override this method and return true.

Id

public string Id { get; }

Property Value

String

CanExecuteSqlQuery

This property specifies whether the FeatureSource can excute a SQL query or not. If it is false, then it will throw exception when these APIs are calleds: ExecuteScalar, ExecuteNonQuery, ExecuteQuery

public bool CanExecuteSqlQuery { get; }

Property Value

Boolean

Remarks:

The default implementation is false.

IsOpen

This property returns true if the FeatureSource is open and false if it is not.

public bool IsOpen { get; }

Property Value

Boolean

Remarks:

Various methods on the FeatureSource require that it be in an open state. If one of those methods is called when the state is not open, then the method will throw an exception. To enter the open state, you must call the FeatureSource's Open method. The method will raise an exception if the current FeatureSource is already open.

Projection

public Projection Projection { get; protected set; }

Property Value

Projection

CanModifyColumnStructure

public bool CanModifyColumnStructure { get; }

Property Value

Boolean

IsInTransaction

This property returns true if the FeatureSource is in a transaction and false if it is not.

public bool IsInTransaction { get; }

Property Value

Boolean

Remarks:

To enter a transaction, you must first call the BeginTransaction method of the FeatureSource. It is possible that some FeatureSources are read-only and do not allow edits. To end a transaction, you must either call CommitTransaction or RollbackTransaction.

IsTransactionLive

This property returns true if the features currently modified in a transaction are expected to reflect their state when calling other methods on the FeatureSource, such as spatial queries.

public bool IsTransactionLive { get; set; }

Property Value

Boolean

Remarks:

The live transaction concept means that all of the modifications you perform during a transaction are live from the standpoint of the querying methods on the object.

As an example, imagine that you have a FeatureSource that has 10 records in it. Next, you begin a transaction and then call GetAllFeatures. The result would be 10 records. After that, you call a delete on one of the records and call the GetAllFeatures again. This time you only get nine records, even though the transaction has not yet been committed. In the same sense, you could have added a new record or modified an existing one and those changes would be considered live, though not committed.

In the case where you modify records -- such as expanding the size of a polygon -- those changes are reflected as well. For example, you expand a polygon by doubling its size and then do a spatial query that would not normally return the smaller record, but instead would return the larger records. In this case, the larger records are returned. You can set this property to be false, as well; in which case, all of the spatially related methods would ignore anything that is currently in the transaction buffer waiting to be committed. In such a case, only after committing the transaction would the FeatureSource reflect the changes.

ProjectionConverter

This property holds the projection object that is used within the FeatureSource to ensure that features inside of the FeatureSource are projected.

public ProjectionConverter ProjectionConverter { get; set; }

Property Value

ProjectionConverter

Remarks:

By default this property is null, meaning that the data being passed back from any methods on the FeatureSource will be in the coordinate system of the raw data. When you specify a projection object in the property, all incoming and outgoing method calls will subject the features to projection.

For example, if the spatial database you are using has all of its data stored in decimal degrees, but you want to see the data in UTM, you would create a projection object that goes from decimal degrees to UTM and set that as the projection. With this one property set, we will ensure that it will seem to you the developer that all of the data in the FeatureSource is in UTM. That means every spatial query will return UTM projected shapes. You can even pass in UTM shapes for the parameters. Internally, we will ensure that the shapes are converted to and from the projection without any intervention on the developer's part.

In fact, even when you override virtual or abstract core methods in the FeatureSource, you will not need to know about projections at all. Simply work with the data in its native coordinate system. We will handle all of the projection at the high level method.

GeoCache

The cache system.

public FeatureCache GeoCache { get; set; }

Property Value

FeatureCache

Remarks:

You must set IsActive to true for the Cache system. The default is not active.

FeatureIdsToExclude

A collection of strings representing record id of features not to get in the Layer.

public Collection<string> FeatureIdsToExclude { get; }

Property Value

Collection<String>

Remarks:

This string collection is a handy place to specify what records not to get from the source. Suppose you have a shape file of roads and you want to hide the roads within a particular rectangle, simply execute GetFeaturesInsideBoundingBox() and add the id of the return features to the collection and forget about them. Since you can set this by Layer it makes is easy to determine what to and what not to.

TransactionBuffer

The TransactionBuffer used in the Transaction System.

public TransactionBuffer TransactionBuffer { get; set; }

Property Value

TransactionBuffer

Remarks:


The Transaction System

The transaction system of a FeatureSource sits on top of the inherited implementation of any specific source, such as Oracle Spatial or Shape files. In this way, it functions the same way for every FeatureSource. You start by calling BeginTransaction. This allocates a collection of in-memory change buffers that are used to store changes until you commit the transaction. So, for example, when you call the Add, Delete or Update method, the changes to the feature are stored in memory only. If for any reason you choose to abandon the transaction, you can call RollbackTransaction at any time and the in-memory buffer will be deleted and the changes will be lost. When you are ready to commit the transaction, you call CommitTransaction and the collections of changes are then passed to the CommitTransactionCore method and the implementer of the specific FeatureSource is responsible for integrating your changes into the underlying FeatureSource. By default the IsLiveTransaction property is set to false, which means that until you commit the changes, the FeatureSource API will not reflect any changes that are in the temporary editing buffer.

In the case where the IsLiveTransaction is set to true, then things function slightly differently. The live transaction concept means that all of the modifications you perform during a transaction are live from the standpoint of the querying methods on the object.

As an example, imagine that you have a FeatureSource that has 10 records in it. Next, you begin a transaction and then call GetAllFeatures. The result would be 10 records. After that, you call a delete on one of the records and call the GetAllFeatures again. This time you only get nine records, even though the transaction has not yet been committed. In the same sense, you could have added a new record or modified an existing one and those changes would be considered live, though not committed.

In the case where you modify records -- such as expanding the size of a polygon -- those changes are reflected as well. For example, you expand a polygon by doubling its size and then do a spatial query that would not normally return the smaller record, but instead would return the larger records. In this case, the larger records are returned. You can set this property to be false, as well; in which case, all of the spatially related methods would ignore anything that is currently in the transaction buffer waiting to be committed. In such a case, only after committing the transaction would the FeatureSource reflect the changes.

MaxRecordsToDraw

public int MaxRecordsToDraw { get; set; }

Property Value

Int32

Constructors

MultipleShapeFileFeatureSource()

This is the default constructor for the class.

public MultipleShapeFileFeatureSource()

Remarks:

This is the default constructor. If you use this constructor then you need to set the required properties manually.

MultipleShapeFileFeatureSource(String)

This is the constructor for the class.

public MultipleShapeFileFeatureSource(string multipleShapeFilePattern)

Parameters

multipleShapeFilePattern String

         This parameter represents the shape file path pattern. The format of it should be
         "C:\MapData\USRoad??.Shp".

Remarks:

This is the constructor for this class. You can pass in a multipleShapeFilePattern like C:\MapData\??lka.shp to use all the shp files in the C:\MapData\ folder with a five letters as its file name without extentsion, the last three should be "lka". And also you can use c:\MapData\USRoad??.shp as the parameter to use all the file which the file name begin with "USRoad" and end with any 2 character shape file; like "USRoadA1.shap" or "USRoad_1.shp".

MultipleShapeFileFeatureSource(String, String)

This is the constructor for the class.

public MultipleShapeFileFeatureSource(string multipleShapeFilePattern, string indexFilePattern)

Parameters

multipleShapeFilePattern String

         This parameter represents the shape file path pattern. The format of it should be
         "C:\MapData\USRoad??.Shp".

indexFilePattern String

         This parameter represents the index file path pattern. The format of it should be
         "C:\MapData\USRoad??.idx".

Remarks:

This is the constructor for this class. You can pass in a multipleShapeFilePattern like C:\MapData\??lka.shp to use all the shp files in the C:\MapData\ folder with a five letters as its file name without extentsion, the last three should be "lka". And also you can use c:\MapData\USRoad??.shp as the parameter to use all the file which the file name begin with "USRoad" and end with any 2 character shape file; like "USRoadA1.shap" or "USRoad_1.shp".

MultipleShapeFileFeatureSource(IEnumerable<String>)

public MultipleShapeFileFeatureSource(IEnumerable<string> shapeFiles)

Parameters

shapeFiles IEnumerable<String>

MultipleShapeFileFeatureSource(IEnumerable<String>, IEnumerable<String>)

This is the constructor for the class.

public MultipleShapeFileFeatureSource(IEnumerable<string> shapeFiles, IEnumerable<string> indexes)

Parameters

shapeFiles IEnumerable<String>

        This parameter represents the shape files to construct the ShapeFileFeatureSource. The format of it should be
        new string[] { "C:\CA_counties.shp", "C:\AZ_counties.shp" }.

indexes IEnumerable<String>

        This parameter represents the shape files to construct the ShapeFileFeatureSource. The format of it should be
         new string[] { "C:\CA_counties.midx", "C:\AZ_counties.midx" }.

Remarks:

This is the constructor for this class. You can pass in a group of shapes and its corresponding indexs like string[] shapeFiles = new string[] { "C:\CA_counties.shp", "C:\AZ_counties.shp" }; string[] indexFiles = new string[] { "C:\CA_counties.midx", "C:\AZ_counties.midx" }; In this way, the MultipleShapeFileFeatureSource will construct from the passing 2 shapes.

Methods

GetShapePathFilenames()

This method gets all the shape's path and filenames are using in this class based on the pass in MultipleShapeFilePattern.

public Collection<string> GetShapePathFilenames()

Returns

Collection<String>

        This method gets all the shape's path and filenames are using in this class based
        on the pass in MultipleShapeFilePattern.

Remarks:

This method gets all the shape's path and filenames are using in this class based on the pass in MultipleShapeFilePattern.

For example:

If you pass in the path "C:\MapData\???.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the shape file in folder "C:\MapData\" which filename only has 3 characters.

If you pass in the path "C:\MapData\USRoad??.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the shape file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.shp or USRoad_A.shp.

GetIndexPathFilenames()

This method gets all the index's path and filenames are using in this class based on the pass in MultipleIndexFilePattern.

public Collection<string> GetIndexPathFilenames()

Returns

Collection<String>

        This method gets all the index's path and filenames are using in this class based
        on the pass in MultipleIndexFilePattern.

Remarks:

This method gets all the index's path and filenames are using in this class based on the pass in MultipleIndexFilePattern.

For example:

If you pass in the path "C:\MapData\???.idx" as the MultipleIndexFilePattern, this method will return a collection which contains all the index file in folder "C:\MapData\" which filename has only 3 characters.

If you pass in the path "C:\MapData\USRoad??.idx" as the MultipleIndexFilePattern, this method will return a collection which contains all the index file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.idx or USRoad_A.idx. By the way, the file named AUSRoadA1.idx and USRoadA1A.idx will NOT included in the returning collection.

BuildIndex(String)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(string multipleShapeFilePattern)

Parameters

multipleShapeFilePattern String
This parameter reprensents the shape file's name in the pattern.For example:If you pass in the path "C:\MapData\???.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the .shp file in folder "C:\MapData\" which filename has only 3 characters.If you pass in the path "C:\MapData\USRoad??.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the shape file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.shp or USRoad_A.shp.

Remarks:

This overload builds an index file with the specified index file name for a group of passed in features.

BuildIndex(String, BuildIndexMode)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(string multipleShapeFilePattern, BuildIndexMode buildIndexMode)

Parameters

multipleShapeFilePattern String
This parameter reprensents the shape file's name in the pattern.For example:If you pass in the path "C:\MapData\???.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the .shp file in folder "C:\MapData\" which finename has only 3 characters.If you pass in the path "C:\MapData\USRoad??.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the shape file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.shp or USRoad_A.shp.

buildIndexMode BuildIndexMode

        This parameter determines what will happen if there is an existing index
        file.

Remarks:

This overload builds an index file with the specified index file name for a group of passed in features.

BuildIndex(String, String)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(string multipleShapeFilePattern, string indexFilePattern)

Parameters

multipleShapeFilePattern String
This parameter reprensents the shape file's name in the pattern.For example:If you pass in the path "C:\MapData\???.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the .shp file in folder "C:\MapData\" which finename has only 3 characters.If you pass in the path "C:\MapData\USRoad??.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the shape file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.shp or USRoad_A.shp.

indexFilePattern String
This parameter reprensents the dindex file's name in the pattern.For example:If you pass in the path "C:\MapData\???.idx" as the MultipleIndexFilePattern, this method will return a collection which contains all the .idx file in folder "C:\MapData\" which finename has only 3 characters.If you pass in the path "C:\MapData\USRoad??.idx" as the MultipleIndexFilePattern, this method will return a collection which contains all the index file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.idx or USRoad_A.idx.

Remarks:

This overload builds an index file with the specified index file name for a group of passed in features.

BuildIndex(String, String, BuildIndexMode)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(string multipleShapeFilePattern, string indexFilePattern, BuildIndexMode buildIndexMode)

Parameters

multipleShapeFilePattern String
This parameter reprensents the shape file's name in the pattern.For example:If you pass in the path "C:\MapData\???.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the .shp file in folder "C:\MapData\" which finename has only 3 characters.If you pass in the path "C:\MapData\USRoad??.shp" as the MultipleShapeFilePattern, this method will return a collection which contains all the shape file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.shp or USRoad_A.shp.

indexFilePattern String
This parameter reprensents the dindex file's name in the pattern.For example:If you pass in the path "C:\MapData\???.idx" as the MultipleIndexFilePattern, this method will return a collection which contains all the .idx file in folder "C:\MapData\" which finename has only 3 characters.If you pass in the path "C:\MapData\USRoad??.idx" as the MultipleIndexFilePattern, this method will return a collection which contains all the index file which begin with "USRoad" and end with and 2 characters in folder "C:\MapData\"; like USRoadA1.idx or USRoad_A.idx.

buildIndexMode BuildIndexMode

        This parameter determines what will happen if there is an existing index
        file.

Remarks:

This overload builds an index file with the specified index file name for a group of passed in features.

BuildIndex(String, String, String, String)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(string multipleShapeFilePattern, string columnName, string regularExpression, string indexFilename)

Parameters

multipleShapeFilePattern String
This parameter is the shape file name pattern that you want to build an index for.

columnName String
The columnName to be used to get the value to match the regex expression.

regularExpression String
This parameter specifies the regex expression to filter out thoese records to build index with.

indexFilename String
This parameter specifies the index file name.

Remarks:

This overload builds an index file with the specified index file name and only build Index for those records satisfied the regularExpression. You can also specify if you want to rebuild an existing index file.

BuildIndex(String, String, String, String, BuildIndexMode)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(string multipleShapeFilePattern, string columnName, string regularExpression, string indexPathFilename, BuildIndexMode buildIndexMode)

Parameters

multipleShapeFilePattern String
This parameter is the shape file name pattern that you want to build an index for.

columnName String
The columnName to be used to get the value to match the regex expression.

regularExpression String
This parameter specifies the regex expression to filter out thoese records to build index with.

indexPathFilename String
This parameter specifies the index file name.

buildIndexMode BuildIndexMode
This parameter determines what will happen if there is an existing index file.

Remarks:

This overload builds an index file with the specified index file name and only build Index for those records satisfied the regularExpression. You can also specify if you want to rebuild an existing index file.

BuildIndex(String[], String[])

This method build spatial index for a passed group of shape files.

public static void BuildIndex(String[] multipleShapeFiles, String[] multipleShapeFileIndexes)

Parameters

multipleShapeFiles String[]

        This parameter represents the shape files to construct the MultipleShapeFileFeatureLayer. The format of it should be
        new string[] { "C:\CA_counties.shp", "C:\AZ_counties.shp" }.

multipleShapeFileIndexes String[]

        This parameter represents the shape files to construct the ShapeFileFeatureLayer. The format of it should be
         new string[] { "C:\CA_counties.midx", "C:\AZ_counties.midx" }.

BuildIndex(String[], String[], BuildIndexMode)

This method build spatial index for a passed group of shape files.

public static void BuildIndex(String[] multipleShapeFiles, String[] multipleShapeFileIndexes, BuildIndexMode buildIndexMode)

Parameters

multipleShapeFiles String[]

        This parameter represents the shape files to construct the MultipleShapeFileFeatureLayer. The format of it should be
        new string[] { "C:\CA_counties.shp", "C:\AZ_counties.shp" }.

multipleShapeFileIndexes String[]

        This parameter represents the shape files to construct the ShapeFileFeatureLayer. The format of it should be
         new string[] { "C:\CA_counties.midx", "C:\AZ_counties.midx" }.

buildIndexMode BuildIndexMode

        This parameter determines whether the index file will be rebuilt if it already
        exists.

GetColumnsCore()

This method returns the columns available for the FeatureSource.

protected Collection<FeatureSourceColumn> GetColumnsCore()

Returns

Collection<FeatureSourceColumn>
This method returns the columns available for the FeatureSource.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

Remarks:

As this is the virtual core version of the Columns method it is intended to be overridden in inherited version of the class. When overriding you will be responsible for getting a list of all of the columns supported by the FeatureSource. In this way the FeatureSource will know what columns are available and will remove any extra columns when making calls to other core methods. For example if you have a FeatureSource that has three columns of information and the user calls a method and requests four columns of information, something they can do with custom fields, we will first compare what they are asking for to the results of the GetColumnsCore. In this way we can strip out custom columns before calling other Core methods which are only responsible for returning data in the FeatureSource. For more information on custom fields you can see the documentation on the OnCustomFieldsFetch.

OpenCore()

This method opens the FeatureSource so that it is initialized and ready to use.

protected void OpenCore()

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has already been opened it will throw an InvalidOperationException.

Remarks:

This protected virtual method is called from the concreate public method Open. The open method play an important role as it is responsible for initializing the FeatureSource. Most methods on the FeatureSource will throw an exception if the state of the FeatureSource is not opened. When the map draws each layer it will open the FeatureSource as one of its first steps, then after it is finished drawing with that layer it will close it. In this way we are sure to release all resources used by the FeatureSource.

When implementing this virtual method consider opening files for file based source, connecting to databases in the database based sources and so on. You will get a chance to close these in the Close method of the FeatureSource.

CloseCore()

This method closes the FeatureSource and releases any resources it was using.

protected void CloseCore()

Remarks:

This protected virtual method is called from the concreate public method Close. The close method plays an important role in the life cycle of the FeatureSource. It may be called after drawing to release any memory and other resources that were allocated since the Open method was called.

It is recommended that if you override this method that you take the following things into account. This method may be called multiple times so we suggest you write the so that that a call to a closed FeatureSource is ignored and does not generate an error. We also suggest that in the close you free all resources that have been opened. Remember that the object will not be destroyed but will be re-opened possibly in the near future.

CommitTransactionCore(TransactionBuffer)

This method will commit the existing transaction to its underlying source of data.

protected TransactionResult CommitTransactionCore(TransactionBuffer transactions)

Parameters

transactions TransactionBuffer

        This parameter encapsulates all of the adds, edits and deleted that make up the
        transaction. You will use this data to write the changes to your underlying data
        source.

Returns

TransactionResult

        The return decimalDegreesValue of this method is a TransactionResult class which gives you the
        status of the transaction you just committed. It includes how many of the updates,
        adds, and deletes were successful and any error that were encountered during the
        committing of the transaction.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which is not in transaction it will throw an InvalidOperationException.

Remarks:

This method will commit the existing transaction to its underlying source of data. It will pass back the results of how the commit went to include any error received. If you are implementing your own FeatureSource then this is one of the crucial methods you must create. It should be fairly straight forward that you will loop through the transaction buffer and add, edit or delete the InternalFeatures in your underlying data source. Remember to build and pass back the TransactionResult class so that users of your FeatureSource can respond to failures you may encounter committing the InternalFeatures. We will handle the end of the transaction and also the cleanup of the transaction buffer. Your task will be to commit the records and produce a TransactionResult return.

The Transaction System

The transaction system of a FeatureSource sits on top of the inherited implementation of any specific source such as Oracle Spatial or Shape files. In this way it functions the same way for every FeatureSource. You start by calling the BeginTransaction. This allocates a collection of in memory change buffers that are used to store changes until you commit the transaction. So for example when you call the Add, Delete or Update method the changes to the feature are stored in memory only. If for any reason you choose to abandon the transaction you can call RollbackTransaction at any time and the in memory buffer will be deleted and the changes will be lost. When you are ready to commit the transaction you call the CommitTransaction and the collections of changes are then passed to the CommitTransactionCore method and the implementer of the specific FeatureSource is responsible for integrating your changes into the underlying FeatureSource. By default the IsLiveTransaction property is set to false which means that until you commit the changes the FeatureSource API will not reflect any changes that are in the temporary editing buffer.

In the case where the IsLiveTransaction is set to true then things function slightly differently. The live transaction concept means that all of the modification you perform during a transaction are live from the standpoint of the querying methods on the object.

To setup an example imagine that you have a FeatureSource that has 10 records in it. Next you begin a transaction and then call GetAllFeatures, the result would be 10 records. After that you call a delete on one of the records and call the GetAllFeatures again, this time you only get nine records. You receive nine records even though the transaction has not yet been committed. In the same sense you could have added a new record or modified an existing one and those changes are considered live though not committed.

In the case where you modify records such as expanding the size of a polygon those changes as well are reflected. So for example you expand a polygon by doubling its size and then do a spatial query that would not normally return the smaller record but would return the larger records, in this case the larger record is returned. You can set this property to be false as well in which case all of the spatial related methods would ignore anything that is currently in the transaction buffer waiting to be committed. In this case only after committing the transaction would the FeatureSource reflect the changes.

GetAllFeaturesCore(IEnumerable<String>)

This method returns all of the InternalFeatures in the FeatureSource.

protected Collection<Feature> GetAllFeaturesCore(IEnumerable<string> returningColumnNames)

Parameters

returningColumnNames IEnumerable<String>

        This parameter allows you to select the field names of the column data you wish
        to return with each Feature.

Returns

Collection<Feature>

        The return decimalDegreesValue is a collection of all of the InternalFeatures in the
        FeatureSource.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

Remarks:

This method returns all of the InternalFeatures in the FeatureSource. You will not need to consider anything about pending transactions as this will be handled in the non Core version of the method.

The main purpose of this method is to be the anchor of all of our default virtual implementations within this class. We wanted as the framework developers to provide you the user with as much default virtual implementation as possible. To do this we needed a way to get access to all of the features. For example, we want to create a default implementation for finding all of the InternalFeatures in a bounding box. Because this is an abstract class we do not know the specifics of the underlying data or how its spatial indexes work. What we do know is that if we get all the records then we can brute force the answer. In this way if you inherited form this class and only implemented this one method we can provide default implementations for virtually every other API.

While this is nice for you the developer if you decide to create your own FeatureSource it comes with a price. The price is that it is very inefficient. In the case we just discussed about finding all of the InternalFeatures in a bounding box we would not want to look at every record to fulfil this method. Instead we would want to override the GetFeaturesInsideBoundingBoxCore and implement specific code that would be fast. For example in Oracle Spatial there is a specific SQL statement to do this operation very quickly. The same holds true with other specific FeatureSource examples.

Most default implementations in the FeatureSource call the GetFeaturesInsideBoundingBoxCore which by default calls the GetAllFeaturesCore. It is our advice that if you create your own FeatureSource that you ALWAYS override the GetFeatureInsideBoundingBox. It will ensure that nearly every other API will operate efficiently. Please see the specific API to determine what method it uses.

GetFeatureIdsCore()

protected Collection<string> GetFeatureIdsCore()

Returns

Collection<String>

GetBoundingBoxCore()

This method returns the bounding box which encompasses all of the features in the FeatureSource.

protected RectangleShape GetBoundingBoxCore()

Returns

RectangleShape

        This method returns the bounding box which encompasses all of the features in the
        FeatureSource.

Exceptions

InvalidOperationException
If the operation is done under source closed state it will throw a InvalidOperationException.

Remarks:

This protected virtual method is called from the concreate public method GetBoundingBox. It does not take into account any transaction activity as this is the responsibility of the concreate public method GetBoundingBox. In this way as a developer if you choose to override this method you do not have to consider transaction at all.

The default implementation of GetBoundingBoxCore uses the GetAllRecordsCore method to calculate the bounding box of the FeatureSource. We strongly recommend that you provide your own implementation for this method that will be more efficient

If you do not override this method the means it gets the BoundingBox is by calling the GetAllFeatureCore method and deriving it from each feature. This is a very inefficient way to get the BoundingBox in most data sources. It is highly recommended that you override this method and replace it with a highly optimized version. For example in a ShapeFile the BoundingBox is in the main header of the file. Similarly if you are using Oracle Spatial you can execute a simple query to get the BoundingBox of all of the record without returning them. In these ways you can greatly improve the performance of this method.

GetCountCore()

This method returns the count of the number of records in this FeatureSource.

protected long GetCountCore()

Returns

Int64

        This method returns the count of the number of records in this
        FeatureSource.

Exceptions

InvalidOperationException
If the operation is done under source closed state it will throw a InvalidOperationException.

Remarks:

This protected virtual method is called from the concreate public method GetCount. It does not take into account any transaction activity as this is the responsibility of the concreate public method GetCount. In this way as a developer if you choose to override this method you do not have to consider transaction at all.

The default implementation of GetCountCore uses the GetAllRecordsCore method to calculate how many records there are in the FeatureSource. We strongly recommend that you provide your own implementation for this method that will be more efficient

If you do not override this method the means it gets the count is by calling the GetAllFeatureCore method and counting each feature. This is a very inefficient way to get the count in most data sources. It is highly recommended that you override this method and replace it with a highly optimized version. For example in a ShapeFile the record count is in the main header of the file. Similarly if you are using Oracle Spatial you can execute a simple query to get the count of all of the record without returning them. In these ways you can greatly improve the performance of this method.

GetFeaturesByIdsCore(IEnumerable<String>, IEnumerable<String>)

This method returns a collection of InternalFeatures by providing a group of Ids.

protected Collection<Feature> GetFeaturesByIdsCore(IEnumerable<string> ids, IEnumerable<string> returningColumnNames)

Parameters

ids IEnumerable<String>

        This parameter represents the group of Ids which uniquely identified the InternalFeatures
        in the FeatureSource.

returningColumnNames IEnumerable<String>

        This parameter allows you to select the field names of the column data you wish
        to return with each Feature.

Returns

Collection<Feature>
This method returns a collection of InternalFeatures by providing a group of Ids.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

ArgumentNullException
If you pass a null as the ids we will throw an ArgumentNullException.

ArgumentNullException
If you pass a null as the returningColumnNames we will throw an ArgumentNullException.

Remarks:

This method returns a collection of InternalFeatures by providing a group of Ids. The internal implementation calls the GetAllFeaturesCore. Because of this if you want an efficient version of this method then we high suggest you override the GetFeaturesByIdsCore method and provide a fast way to find a group of InternalFeatures by their Id.

GetFeaturesInsideBoundingBoxCore(RectangleShape, IEnumerable<String>)

This method returns all of the InternalFeatures of this FeatureSource inside of the specified bounding box.

protected Collection<Feature> GetFeaturesInsideBoundingBoxCore(RectangleShape boundingBox, IEnumerable<string> returningColumnNames)

Parameters

boundingBox RectangleShape

        This parameter represents the bounding box you with to find InternalFeatures inside
        of.

returningColumnNames IEnumerable<String>

        This parameter allows you to select the field names of the column data you wish
        to return with each Feature.

Returns

Collection<Feature>

        The return decimalDegreesValue is a collection of all of the InternalFeatures that are inside of the
        bounding box.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

ArgumentNullException
If you pass a null as the returningColumnNames we will throw an ArgumentNullException.

ArgumentNullException
If you pass a null as the boundingBox we will throw an ArgumentNullException.

Remarks:

This method returns all of the InternalFeatures of this FeatureSource inside of the specified bounding box. If you are overriding this method you will not need to consider anything about transactions as this is handled by the concreate version of this method.

The default implementation of GetFeaturesInsideBoundingBoxCore uses the GetAllRecordsCore method to determine which InternalFeatures are inside of the bounding box. We strongly recommend that you provide your own implementation for this method that will be more efficient. It is especially important for this method as many other default virtual methods use this for their calculations. We highly recommend when you override this method that you use any spatial indexes you have at your disposal to make this method as fast as possible.

GetFeaturesOutsideBoundingBoxCore(RectangleShape, IEnumerable<String>)

This method returns all of the InternalFeatures of this FeatureSource outside of the specified bounding box.

protected Collection<Feature> GetFeaturesOutsideBoundingBoxCore(RectangleShape boundingBox, IEnumerable<string> returningColumnNames)

Parameters

boundingBox RectangleShape

        This parameter represents the bounding box you with to find InternalFeatures outside
        of.

returningColumnNames IEnumerable<String>

        This parameter allows you to select the field names of the column data you wish
        to return with each Feature.

Returns

Collection<Feature>

        This method returns all of the InternalFeatures of this FeatureSource outside of the
        specified bounding box.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

ArgumentNullException
If you pass a null as the returningColumnNames we will throw an ArgumentNullException.

ArgumentNullException
If you pass a null as the boundingBox we will throw an ArgumentNullException.

Remarks:

This method returns all of the InternalFeatures of this FeatureSource outside of the specified bounding box. If you are in a transaction and that transaction is live then it will also take that into consideration.


The default implementation of GetFeaturesOutsideBoundingBoxCore uses the GetAllRecordsCore method to determine which InternalFeatures are outside of the bounding box. We strongly recommend that you provide your own implementation for this method that will be more efficient

GetFeaturesWithinDistanceOfCore(BaseShape, GeographyUnit, DistanceUnit, Double, IEnumerable<String>)

This method returns a collection of InternalFeatures that are within a certain distance of the TargetShape.

protected Collection<Feature> GetFeaturesWithinDistanceOfCore(BaseShape targetShape, GeographyUnit unitOfData, DistanceUnit distanceUnit, double distance, IEnumerable<string> returningColumnNames)

Parameters

targetShape BaseShape
The shape you wish to find InternalFeatures within a distance of.

unitOfData GeographyUnit

        This parameter is the unit of data that the FeatureSource and TargetShape are
        in.

distanceUnit DistanceUnit

        This parameter specifies the unit of the distance parameter such as feet, miles
        or kilometers etc.

distance Double

        This parameter specifies the distance in which to find InternalFeatures around the
        TargetShape.

returningColumnNames IEnumerable<String>

        This parameter allows you to select the field names of the column data you wish
        to return with each Feature.

Returns

Collection<Feature>

        This method returns a collection of InternalFeatures that are within a certain distance
        of the TargetShape.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

ArgumentNullException
If you pass a null as the targetShape we will throw an ArgumentNullException.

ArgumentNullException
If you pass a null as the returningColumnNames we will throw an ArgumentNullException.

ArgumentOutOfRangeException
If you pass in a unitOfData that is not defined it will throw a ArgumentOutOfRangeException.

ArgumentOutOfRangeException
If you pass in a distanceUnit that is not defined it will throw a ArgumentOutOfRangeException.

ArgumentException
If you pass in a targetShape which is invalid we will throw an ArgumentException.

Remarks:

This method returns a collection of InternalFeatures that are within a certain distance of the TargetShape. It is important to note that the TargetShape and the FeatureSource use the same unit such as feet or meters. If they do not then the results will not be predictable or correct. If there is a current transaction and it is marked as live then the results will include any transaction Feature that applies.

The implementation we provided create a bounding box around the TargetShape using the distance supplied and then queries the features inside of it. This may not the most efficient method for this operation. If you underlying data provider exposes a more efficient way we recommend you override the Core version of this method and implement it.

The default implementation of GetFeaturesWithinDistanceOfCore uses the GetFeaturesInsideBoundingBoxCore method for speed. We strongly recommend that you provide your own implementation for this method that will be more efficient. We recommend when you override GetFeaturesInsideBoundingBoxCore method that you use any spatial indexes you have at your disposal to make this method as fast as possible.

GetFeaturesNearestToCore(BaseShape, GeographyUnit, Int32, IEnumerable<String>)

This method returns a user defined number of InternalFeatures that are closest to the TargetShape.

protected Collection<Feature> GetFeaturesNearestToCore(BaseShape targetShape, GeographyUnit unitOfData, int maxItemsToFind, IEnumerable<string> returningColumnNames)

Parameters

targetShape BaseShape
This parameter is the shape you should to find close InternalFeatures to.

unitOfData GeographyUnit

        This parameter is the unit of what the TargetShape and the FeatureSource is in
        such as feet, meters etc.

maxItemsToFind Int32

        This parameter defines how many close InternalFeatures to find around the
        TargetShape.

returningColumnNames IEnumerable<String>

        This parameter allows you to select the field names of the column data you wish
        to return with each Feature.

Returns

Collection<Feature>

        This method returns a user defined number of InternalFeatures that are closest to the
        TargetShape.

Exceptions

InvalidOperationException
In the event you attempt to call this method on a feature source which has not been opened it will throw an InvalidOperationException.

ArgumentNullException
If you pass a null as the targetShape we will throw an ArgumentNullException.

ArgumentNullException
If you pass a null as the returningColumnNames we will throw an ArgumentNullException.

ArgumentOutOfRangeException
If you pass in a maxItemsToFind that is not greater than 0 it will throw a ArgumentOutOfRangeException.

ArgumentException
If you pass in a targetShape which is invalid we will throw an ArgumentException.

Remarks:

This method returns a user defined number of InternalFeatures that are closest to the TargetShape. It is important to note that the TargetShape and the FeatureSource use the same unit such as feet or meters. If they do not then the results will not be predictable or correct. If there is a current transaction and it is marked as live then the results will include any transaction Feature that applies.

The implementation we provided create a small bounding box around the TargetShape and then queries the features inside of it. If we reach the number of items to find then we measure the returned InternalFeatures to find the nearest. If we do not find enough records we scale up the bounding box and try again. As you can see this is not the most efficient method. If you underlying data provider exposes a more efficient way we recommend you override the Core version of this method and implement it.

The default implementation of GetFeaturesNearestCore uses the GetFeaturesInsideBoundingBoxCore method for speed. We strongly recommend that you provide your own implementation for this method that will be more efficient. We recommend when you override GetFeaturesInsideBoundingBoxCore method that you use any spatial indexes you have at your disposal to make this method as fast as possible.

Events

DrawingProgressChanged

public event EventHandler<DrawingProgressChangedEventArgs> DrawingProgressChanged;

GettingColumns

public event EventHandler<GettingColumnsFeatureSourceEventArgs> GettingColumns;

GottenColumns

public event EventHandler<GottenColumnsFeatureSourceEventArgs> GottenColumns;

GettingFeaturesByIds

public event EventHandler<GettingFeaturesByIdsFeatureSourceEventArgs> GettingFeaturesByIds;

GettingFeaturesForDrawing

public event EventHandler<GettingFeaturesForDrawingFeatureSourceEventArgs> GettingFeaturesForDrawing;

CustomColumnFetch

This event is raised when fields are requested in a feature source method that do not exist in the feature source. It allows you to supplement the data from any outside source you have.

public event EventHandler<CustomColumnFetchEventArgs> CustomColumnFetch;

Remarks:

This event is raised when fields are requested in a feature source method that do not exist in the feature source. It allows you to supplement the data from any outside source you have.

It is used primarily when you have data relating to a particular feature or set of features that is not within source of the data. For example, you may have a shape file of the world whose .dbf component describes the area and population of each country. Additionally, in an outside SQL Server table, you may also have data about the countries, and it is this data that you wish to use for determining how you want to color each country.

To integrate this SQL data, you simply create a file name that does not exist in the .dbf file. Whenever Map Suite is queried to return records that specifically require this field, the FeatureSource will raise this event and allow you the developer to supply the data. In this way, you can query the SQL table and store the data in some sort of collection, and then when the event is raised, simply supply that data.

As this is an event, it will raise for each feature and field combination requested. This means that the event can be raised quite often, and we suggest that you cache the data you wish to supply in memory. We recommend against sending out a new SQL query each time this event is raised. Image that you are supplementing two columns and your query returns 2,000 rows. This means that if you requested those fields, the event would be raised 4,000 times.

CommittingTransaction

This event is raised after the CommitTransaction method is called, but before the CommitTransactionCore is called. This allows you access to the TransactionBuffer before the transaction is committed. It also allows you to cancel the pending commit of the transaction.

public event EventHandler<CommittingTransactionEventArgs> CommittingTransaction;

Remarks:

This event is raised before the CommitTransactionCore is called and allows you access to the TransactionBuffer before the transaction is committed. It also allows you to cancel the pending transaction. The TransactionBuffer is the object that stores all of the pending transactions and is accessible through this event to allow you to either add, remove or modify transactions.

In the event that you cancel the CommitTransaction method, the transaction remains intact and you will still be editing. This makes it a nice place to possibly check for connectivity before the TransactionCore code is run, which is where the records are actually committed. Calling the RollBackTransaction method is the only way to permanently cancel a pending transaction without committing it.

CommittedTransaction

This event is raised after the CommitTransaction and the CommitTransactionCore are called and allows you access to the TransactionBuffer and the TransactionResults object before CommitTransaction method is returned.

public event EventHandler<CommittedTransactionEventArgs> CommittedTransaction;

Remarks:

This event is raised after the CommitTransactionCore is called and allows you access to the TransactionBuffer and the TransactionResults object before CommitTransaction method is returned.

With this event, you can analyse the results of the transaction and do any cleanup code necessary. In the event some of the records did not commit, you can handle those items here. The TransactionResults object is passed out of the CommitTransaction method so you could analyze it then; however, this is the only place where you have access to both the TransactionResults object and the TransactionBuffer object at the same time. These are useful together to try and determine what went wrong and possibly try and re-commit them.

At the time of this event you will technically be out of the current transaction.

OpeningFeatureSource

This event is called before the opening of the FeatureSource.

public event EventHandler<OpeningFeatureSourceEventArgs> OpeningFeatureSource;

Remarks:

This event is called before the opening of the FeatureSource. Technically, this event is called after the calling of the Open method on the FeatureSource, but before the protected OpenCore method.

It is typical that the FeatureSource may be opened and closed may times during the life cycle of your application. The type of control the MapEngine is embedded in will dictate how often this happens. For example, in the case of the Web Edition, each time a FeatureSource is in the Ajax or Post Back part of the page cycle, it will close the FeatureSource before returning back to the client. This is to conserve resources, as the web is a connection-less environment. In the case of the Desktop Edition, we can keep the FeaureSources open, knowing that we can maintain a persistent connection.

OpenedFeatureSource

This event is called after the opening of the FeatureSource.

public event EventHandler<OpenedFeatureSourceEventArgs> OpenedFeatureSource;

Remarks:

This event is called after the opening of the FeatureSource. Technically, this event is called after the calling of the Open method on the FeatureSource and after the protected OpenCore method is called.

It is typical that the FeatureSource may be opened and closed may times during the life cycle of your application. The type of control the MapEngine is embedded in will dictate how often this happens. For example, in the case of the Web Edition, each time a FeatureSource is in the Ajax or Post Back part of the page cycle, it will close the FeatureSource before returning back to the client. This is to conserve resources, as the web is a connection-less environment. In the case of the Desktop Edition, we can keep the FeaureSources open, knowing that we can maintain a persistent connection.

ClosingFeatureSource

This event is called before the closing of the FeatureSource.

public event EventHandler<ClosingFeatureSourceEventArgs> ClosingFeatureSource;

Remarks:

This event is called before the closing of the FeatureSource. Technically, this event is called after the calling of the Close method on the FeatureSource, but before the protected CloseCore method.

It is typical that the FeatureSource may be opened and closed may times during the life cycle of your application. The type of control the MapEngine is embedded in will dictate how often this happens. For example, in the case of the Web Edition, each time a FeatureSource is in the Ajax or Post Back part of the page cycle, it will close the FeatureSource before returning back to the client. This is to conserve resources, as the web is a connection-less environment. In the case of the Desktop Edition, we can keep the FeaureSources open, knowing that we can maintain a persistent connection.

ClosedFeatureSource

This event is called after the closing of the FeatureSource.

public event EventHandler<ClosedFeatureSourceEventArgs> ClosedFeatureSource;

Remarks:

This event is called after the closing of the FeatureSource. Technically, this event is called after the calling of the Close method on the FeatureSource and after the protected CloseCore method.

It is typical that the FeatureSource may be opened and closed may times during the life cycle of your application. The type of control the MapEngine is embedded in will dictate how often this happens. For example, in the case of the Web Edition, each time a FeatureSource is in the Ajax or Post Back part of the page cycle, it will close the FeatureSource before returning back to the client. This is to conserve resources, as the web is a connection-less environment. In the case of the Desktop Edition, we can keep the FeaureSources open, knowing that we can maintain a persistent connection.