Pitney Bowes MapXtreme - Manual (Page 509)

Appendix D: Extensible Data Providers
Advanced Topics / Important Considerations
MapXtreme v7.1 516 Developer Guide
Persistence Providers
MapXtreme offers support for saving data access information, namely ITableDefinitions and
IDataSourceDefinitions, to a MapXtreme XML-based workspace (.MWS). This is an optional
component of the Extensible Data Provider that you may wish to take advantage of if you need to
share your workspace with others or to simply re-use the information at a later time.
To add persistence support to your Extensible Data Provider, in its simplest form, you would write a
persistence provider class that implements the MapInfo.Data.Provider.IMxpPersistenceProvider
interface.
For a more sophisticated persistence provider, consider providing a schema to support XML
validation of the resulting workspace file. This would only be necessary if you have an explicit
requirement, as MapXtreme does not automatically validate workspace XML.
You may also consider writing your persistence provider as its own assembly. Providers may be pre-
loaded independent of the remaining extensible data provider components. A provider assembly
would defer the loading of the remaining components by controlling just-in-time loading of the data
provider when and if it is explicitly needed.
How Are Persistence Providers Used?
Persistence providers are managed in a PersistenceProviderCollection on the Catalog. This
collection may be automatically initialized during session startup when MapXtreme searches the
assemblies in a default location for persistence providers they might contain. The default location is
\Program Files\Common Files\MapInfo\MapXtreme\7.x.x\SessionEventHandlers. Providers can also
be programmatically added into the PersistenceProviderCollection using its Add and
AddFromFolder methods.
When saving session context to a MapInfo workspace file (.MWS) via the
MapInfo.Persistence.WorkspacePersistence class, the PersistenceProviderCollection is consulted
for any tables in the catalog that were opened from an Extensible Data Provider. If a persistence
provider is identified for that data provider, it is used to persist the extensible table information into
the workspace. Similarly, when a workspace is being loaded, the collection of available persistence
providers is searched to identify a data provider capable of understanding the custom tags in the
workspace file associated with an Extensible Data Provider table.
Implementing Your Persistence Provider
In order for the PersistenceProviderCollection.AddFromFolder method to load your persistence
provider class, it must contain a public, zero-argument constructor signature. This is the same
method used internally during MapXtreme’s session initialization. Additional constructor signatures
can be supplied to support programmatic use with the PersistenceProviderCollection.Add method.
MapXtreme provides an abstract base class named AbstractMxpPersistenceProvider you may wish
to use as a starting point for implementing your persistence provider class.
One of the things you must provide in your persistence provider are methods that check whether
there is a supported data provider for your persistence provider, a supported entity name (for the
XML tags) and a supported schema namespace. This is done by implementing the three inquiry
methods included in the IMxpPersistenceProvider interface.