This lesson covers some general topics of interest to developers working with the GeoCalc tool kit. These topics include:
When a GeoCalc object is created, memory is allocated for the object. When the object is no longer needed, the memory used by the object should be freed so that it can be used for other purposes. Many GeoCalc objects implement the System::IDisposable interface, which is provided by the .NET framework. Such objects will have a method called Dispose, which is used to indicate that the object is no longer needed and that the memory used by the object can be freed.
Here is an example of how to use the Dispose method:
Dim gcDataSource As New DataSourceComponent
gcDataSource.LoadFile("c:\\bmg\\GeoCalcNET\\data\\geocalc.xml")
Dim cs As ProjectedCoordSys = gcDataSource.GetProjectedCoordSys("BMG", "UTM-19N")
cs.Dispose()
gcDataSource.Dispose()
DataSourceComponent gcDataSource = new DataSourceComponent();
gcDataSource.LoadFile("c:\\bmg\\GeoCalcNET\\data\\geocalc.xml");
ProjectedCoordSys cs = gcDataSource.GetProjectedCoordSys("BMG", "UTM-19N");
cs.Dispose();
gcDataSource.Dispose();
The Dispose method should be used to free the memory associated with the following objects:
Objects in the GeoCalcNET namespace that were created using the "new" keyword
Objects returned by the DataSourceComponent::Get methods
CoordSys objects returned by the DataSourceComponent::CoordSysFromGML, ImportCoordSysFromFile, ImportCoordSysFromString, and ImportCoordSysFromStrings methods
Serializable objects produced by the ObjectPicker::Show, DataSourceEditor::Show, and DataSourcePicker::Show methods
The DatumShiftCollection produced by the DatumShiftPicker::Show method
All Serializable objects that are stored in the GeoCalc DataSourceComponent must have at least one identifier, and many objects have multiple identifiers. An identifier, combined with an object type, is enough information to uniquely identify any object in the DataSourceComponent. An identifier consists of a pair of strings referred to as the issuer and the code. For example, there is a ProjectedCoordSys defined in geocalc.xml that has an identifier where issuer = "BMG" and code = "UTM-19N". This object is uniquely identified in the DataSourceComponent by this information:
|
Object Type: |
|
|
Issuer: |
BMG |
|
Code: |
UTM-19N |
The issuer of an identifier is the source that provided the definition for the object. Many objects in the supplied data source files have an identifier where the issuer is equal to "BMG", which indicates that Blue Marble Geographics has provided the definition. Some other objects have an identifier where the issuer is equal to "EPSG", which indicates that the definition came from the EPSG database. All objects in the GeoCalc DataSourceComponent must have an identifier where the issuer is equal to "GC".
The code of an identifier is a value that distinguishes an object from other objects of the same type defined by the same issuer.
The identifiers for a Serializable object are stored in the IdentifierCollection that can be accessed through the Serializable::Identifiers property. The IdentifierCollection returned by this property provides the functionality to get the identifiers and also to add, remove, and change the identifiers.
When an unexpected or problematic condition occurs within GeoCalc during runtime, a GeoCalcException will be thrown. When an exception is thrown by some method, the exception will travel down the call stack until it is either caught by a try-catch statement or it reaches the bottom of the call stack. If an exception reaches the bottom of the call stack without being caught, it will cause the application to crash. Therefore, it is a good practice to catch all exceptions.
The properties on the GeoCalcException object will provide some information about why the exception was thrown. The most useful of these is the ErrorCode property, which returns a member of the GeoCalcException::Code enumeration. This value will indicate the general nature of the condition that caused the exception to be thrown. The InnerMessage property can then be used to get a string that gives a verbose description of the exception.
For example, the DataSourceComponent::GetProjectedCoordSys method will throw a GeoCalcException if the specified identifier does not exist in the DataSourceComponent. Here is an example of how to catch this exception:
Try
cs = gcDataSource.GetProjectedCoordSys("NOT_A_VALID_ISSUER", "NOT_A_VALID_CODE")
Catch ex As GeoCalcException
If ex.ErrorCode = GeoCalcException.Code.IdentifierNotFound Then
MessageBox.Show("Invalid identifier")
End If
End Try
try
{
cs = gcDataSource.GetProjectedCoordSys("NOT_A_VALID_ISSUER", "NOT_A_VALID_CODE");
}
catch(GeoCalcException ex)
{
if(ex.ErrorCode == GeoCalcException.Code.IdentifierNotFound)
{
MessageBox.Show("Invalid Identifier");
}
}