ICustomDataSet Interface
Interface for a custom dataset.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECustomObjects assembly)
Syntax
public interface ICustomDataSetRemarks
A custom dataset is an object written by an application developer that extends the Carmenta Engine functionality when some non-standard feature is required. It is typically used to read some data format for which Carmenta Engine has no standard reader. The custom dataset is just a regular class that can be written in C++, Java or any Microsoft .NET language like C#, that implements the ICustomDataSet interface. If the dataset reads raster data, it should also implement the ICustomRasterDataSet interface.
In addition to these interface, a custom dataset must also provide an object to be returned from the Query method, implementing the IQueryResult interface.
The custom dataset can be used directly in a map configuration using a CustomDataSetProxy object. The proxy works as regular Carmenta Engine dataset, but delegates most calls to the custom object. Please see CustomDataSetProxy for more information how to configure and load the custom object.
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.
Carmenta Engine 5 can use background threads to read from a custom dataset. Carmenta Engine 5 will lock the dataset so it can be modified safely during a call to one of the ICustomDataSet members but it must be locked explicitly by an application, by using an instance of the Guard class, before it or any feature it contains are modified as a result from an other call.
To lock a custom dataset instantiate a Guard with the CustomDataSetContext that was passed in the call to InitNew.
More information can be found in Carmenta Engine Threading Model.
Optimizing the performance of custom datasets using dynamic caching
The presentation of features from custom datasets returning static data can be cached under a TileLayer like any other static data.
For custom datasets returning dynamic data that is frequently changing, it is possible to support the dynamic cache modes of OrdinaryLayer. Compared to using an uncached layer, this could give a significant increase in performance and frame rate. To support dynamic caching, you will need to do two things:
Whenever you add, modify or remove features in the dataset, you should call one or more of the CustomDataSetContext.RefreshFeaturePresentation, CustomDataSetContext.RefreshAllFeaturePresentation and CustomDataSetContext.RemoveFeaturePresentation methods, as appropriate.
Your custom dataset class must implement the ISupportsDynamicCaching marker interface. This signals to the CustomDataSetProxy that you do indeed support dynamic caching. Without this, the proxy will throw an exception if used in a cached layer.
You don't need to change anything else. The query method should still return the same features as it would without caching. However, if the presentation for a feature is already cached by the layer, the feature will not be processed any further.
For dynamic caching to be effective, the dataset should cache its own data as complete features, ready to be returned by the query method, at least all features for the currently active view area. Otherwise the overhead of recreating the features in every query can easily become the bottleneck, and the caching of the presentation will not help much.
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 object 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 CreatesReferences property when the proxy determines whether features returned by the custom dataset should be disposed automatically or not.
DataSetInfo
It is possible to let the custom dataset implementation to define the DataSetInfo for instances of the custom dataset class, and for data files that the custom dataset can read. To support this, the dataset implementation should also implement ICustomDataSetInfoProvider.
Platforms
Windows, Linux, Android
See Also
Reference
CustomObjects Module
CustomDataSetProxy
ICustomRasterDataSet
ICustomDataSetInfoProvider
ICustomOperator
ICustomVisualizer
ICustomSymbol
ICustomPropagation
IMinimizeGarbageCollection
ICustomDataSet Members
The ICustomDataSet type has the following members.
Properties
| Name | Description |
|---|---|
| Bounds | Gets the bounds of the dataset. |
| CreatesReferences | Gets a value that indicates if features returned by the dataset are read-only references. |
| Crs | Gets the coordinate reference system used by the dataset. |
| DataCoverage | Gets the data coverage of the dataset. |
Methods
| Name | Description |
|---|---|
| Clone | Called to create a copy of the custom object. |
| FlushCache | Flushes all internal caches held by the custom dataset. |
| GetFeature | Reads a feature with a specific identifier. |
| InitNew | Called when the CustomDataSetProxy is initialized, or when a custom dataset instance is attached to a CustomDataSetProxy. |
| Query | Gets all features matching the query parameters. |