Pitney Bowes MapXtreme - Manual (Page 512)

Appendix D: Extensible Data Providers
Advanced Topics / Important Considerations
MapXtreme v7.1 519 Developer Guide
the ITableDefinition and ITable interfaces. The ITableDefinition and IDataSourceDefinition interfaces
must also provide meaningful overrides to the Equals method in order for deserialization to work
properly.
The classes implementing ITableMetadata are not required to be explicitly serializable, although
there are practical reasons to do so. If not serializable, the deserialization of their respective table
and data source instances may need to reconstruct them, and the re-acquisition of that metadata
could be potentially expensive in terms of performance.
To assist you, the Extensible Data Provider API provides serializable abstract base classes provided
for each of these interfaces. Serialization support is also provided for the relevant properties being
managed by their default implementations.
How do I serialize a class?
In .NET terms, a class is made serializable through some combination of implementing the
ISerializable interface from the System.Runtime.Serialization namespace and/or applying the
[Serializable] attribute to the class definition. Provider developers are free to follow general guidance
regarding .NET serialization in providing your implementation; however, we strongly recommend
applying both – particularly if deriving your classes from the abstract base classes provided.
What if I decide not to support serialization?
We recommend that you provide serialization support in your extensible data provider so you can
provide better and broader support to application developers who will be employing your provider as
a component of their solution. However, there is no strict requirement that a provider implementation
must support serialization. In fact, in some cases there are legitimate reasons why providing this
support is fundamentally difficult or unreliable.
Application developers may be able to use .NET reflection APIs to discover whether or not your
provider appears to support serialization; however, this still may not provide them with everything
they need to know regarding how to properly employ your provider in an application with state
management requirements. We strongly encourage you to provide documentation that includes
specific information regarding if/how your provider implementation can be used as a component for
such solutions.
Serialization and Dependent Relationships
MapXtreme’s Extensible Data Provider includes many dependent relationships that exist amongst
the required and recommended classes. An ITableDefinition contains an IDataSourceDefinition
property. An IDataSource also contains an IDataSourceDefinition and an ITable contains
IDataSource, ITableMetadata, and ITableDefinition properties.
As a rule, you may not need to serialize any property whose references may be shared. For
example, the IDataSourceDefinition property on ITableDefinition may represent a data source
definition that gets re-used to open multiple tables. You do not need to include it in the serialization
of the class implementing ITableDefinition. The same is true for the IDataSource and ITableDefinition
properties within ITable.
We do recommend including the definition properties when serializing – even if they are later
overwritten to use a shared reference.