CustomDataSetAdapter Class
Adapter class that can be used as a base-class to simplify the implementation of a custom dataset.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECustomObjects assembly)
Syntax
public abstract class CustomDataSetAdapter : ICustomDataSetRemarks
The CustomDataSetAdapter class is an adapter class that is intended to be used as a base-class to simplify an implementation of the ICustomDataSet interface.
To implement a basic custom dataset using this class do the following:
Inherit a class from CustomDataSetAdapter.
Call the base-class constructor and specify which Crs the custom dataset uses and whether it returns cached read-only features or modifiable features.
Override the OnQuery method to return the features that match the query parameters.
Override the OnClone method to return a copy of the custom dataset.
Add the IMinimizeGarbageCollection interface to .NET or Java implementations that do not cache objects between updates.
The CustomDataSetAdapter class also provides several other virtual methods that you can choose to override to customize the behavior of the custom dataset. The Custom DataSet Sample demonstrates how this class can be used to implement a custom dataset.
Exceptions that are thrown by custom object implementations will be logged and then propagated by Carmenta Engine as an EngineException to the application. Also, the only way a C++ custom object implementation can include a relevant error message to an application is by throwing an EngineException.
This adapter class is suitable for many custom dataset implementations but if you need more control you can always implement the ICustomDataSet interface directly instead.
The CustomDataSetAdapter implements the ICustomDataSet interface itself and classes that inherit from CustomDataSetAdapter should not override any of the ICustomDataSet members even though they might be visible in the subclass.
Also, CustomDataSetAdapter implementations are subject to the same threading and locking restrictions as classes that implement the ICustomDataSet interface directly. Please see ICustomDataSet for more information.
Optimizing the performance of .NET and Java custom objects
Custom objects that are implemented in .NET or Java, both of which use a garbage collector to manage memory, can generate a lot of temporary object instances that must be collected and finalized by the garbage collector. These temporary objects can, depending on how many times a custom object is called during a typical update cycle, generate so much extra work for the garbage collector that it has a significant impact on performance.
In many cases you can improve the performance by adding the IMinimizeGarbageCollection interface to the custom dataset implementation. This tells Carmenta Engine that reference objects passed to, and returned from, the custom object should be disposed automatically which decreases the work that must be performed by the garbage collector.
IMinimizeGarbageCollection works in conjunction with the readOnlyFeatures argument, passed to the constructor, when the proxy determines whether features returned by the custom dataset should be disposed automatically or not.
Inheritance Hierarchy
System.Object (not available in C#)
CustomDataSetAdapter
Platforms
Windows, Linux, Android
CustomDataSetAdapter Members
The CustomDataSetAdapter type has the following members.
Constructors
| Name | Description |
|---|---|
| CustomDataSetAdapter | Initializes a new instance of the CustomDataSetAdapter class. |
Properties
| Name | Description |
|---|---|
| Context | Gets the CustomDataSetContext that was used to initialize this CustomDataSetAdapter. |
| Crs | Gets the Crs that this CustomDataSetAdapter uses. |
Methods
| Name | Description |
|---|---|
| OnCalculateBounds | Called to return the bounds of all features in the custom dataset. |
| OnCalculateDataCoverage | Called to return all areas where the custom dataset has data. |
| OnClone | Called to create a copy of the custom dataset. This method must be implemented. |
| OnFlushCache | Called to flush any internal caches. |
| OnGetFeature | Called to find the Feature with the specified id. |
| OnInitialize | Called when the custom dataset is initialized. |
| OnQuery | Called to find all features that match the specified query parameters. This method must be implemented. |