[mapguide-users] Re: Upgrading MaestroAPI

[Jackie Ng]

There is a reason for this style of API in Maestro

A fair chunk of the Maestro API (basically any class under
OSGeo.MapGuide.ObjectModels) is code generated from the xsd files (because
having to write all these classes by hand would take an eternity). Now the
old Maestro API did this as well, but how it handled various schema versions
(and the new features/properties exposed in newer versions) was done in a
very monkey-patched manner.

For this iteration of the Maestro API, we have generated classes for *each*
revision of each schema, and we use interfaces to wrap the common elements.
This is why you have an ILayerDefinition instead of a LayerDefinitionType,
an IFeatureSource instead of FeatureSourceType, an IMapDefinition instead of
a MapDefinitionType, an IWebLayout instead of WebLayoutType, etc, etc, etc.

This allows the Maestro API to understand and support *all* known schema
versions and makes it very easy for us to add support for newer schema
revisions as they are introduced by having them implementing these
interfaces.

Now a consequence of this design is that we cannot expose such generated
classes through the API. For example we can't have an API return a
LayerDefinitionType because a LayerDefinitionType has 5 different versions
generated, but we can return a ILayerDefinition because all 5 different
versions implement this interface. And we can support newer Layer Definition
revisions for this API by having the generated class implement the same
interface.

So how does this go all the way back to your original question? Those layer
and group collections are collections of these generated classes, so we
cannot expose them through the Maestro API as already explained.

So as a general hint in terms of migrating code, if a 2.x API exposed a
collection, the 4.0 version will expose an IEnumerable<T> along with a
method to add and item of type T and a method to remove an item of type T.
The type T itself will also most likely be an interface (remembering that
generated concrete types are never exposed). Every generated class will have
a corresponding interface.

- Jackie


--
View this message in context: http://osgeo-org.1803224.n2.nabble.com/Upgrading-MaestroAPI-tp7019938p7020153.html
Sent from the MapGuide Users mailing list archive at Nabble.com.