= MaestroAPI 2.1 changes =

== ServerConnectionI creation ==

The public constructors of HttpServerConnection and LocalNativeConnection are now deprecated. They will be eventually removed in a future release.

The current way to create a http server connection for example, is like this:

{{{
MaestroAPI.ServerConnectionI connection = new MaestroAPI.HttpServerConnection(url, sessionID, locale);
}}}

The new way to create a http server connection, is like this:
{{{
MaestroAPI.ServerConnectionI connection = MaestroAPI.ConnectionProviderRegistry.CreateConnection("Maestro.Http", "Url=" + url + ";SessionId=" + sessionID + ";Locale=" + locale + ";AllowUntestedVersion=true");
}}}

A xml provider registry (ConnectionProviders.xml) contains all the known implementations of ServerConnectionI. This file must be in the same path as the MaestroAPI dll.

The reason for this change is that it allows us to easily include a new implementation of ServerConnectionI in the future as part of the MaestroAPI dll, or as an external dll that references the MaestroAPI dll. For example, one could implement ServerConnectionI for the [http://www.georest.org GeoREST] MapGuide extension in a custom dll, register this dll into the ConnectionProviders.xml and be able to use this implementation straight away assuming you know the initialization parameters for this particular implementation.

For convenience, a helper utility class (ConnectionFactory) exists so that you can create your connections using your existing signatures. For example to create a http server connection using the helper class is like this:

{{{
MaestroAPI.ServerConnectionI connection = MaestroAPI.ConnectionFactory.CreateHttpConnection(url, sessionID, locale);
}}}

== !FeatureSetReader changes ==

FeatureSetReader is now an abstract class with 2 implementations:
 * !XmlFeatureSetReader (returned when using !HttpServerConnection)
 * !MgFeatureSetReader (returned when using !LocalNativeConnection)

Associated classes such as !FeatureSetRow and !FeatureSetColumn are also abstract and have matching Xml* and Mg* implementations

The !FeatureSetColumn used when describing a feature source schema is now an internal !ClassPropertyColumn sub-class.

!FeatureSetReader also implements the ADO.net IDataReader interface and !FeatureSetRow implements the ADO.net IDataRecord interface, so now these classes can be used wherever an IDataReader or IDataRecord are used.

!FeatureSetReader also implements the IEnumerable<IDataRecord> interface meaning you can now iterate using the foreach language keyword.

Example (C#):
{{{
FeatureSetReader reader = ...;
foreach(FeatureSetRow row in reader)
{
    //Do something with the row
    ...
}
}}}

From a consuming client's perspective, nothing needs to change. ServerConnectionI and its ilk still return FeatureSetReader.

== Coordinate System APIs ==

Like !FeatureSetReader the Coordinate System APIs have changed so that there is a interface/abstract class with http/native specific implementations. This is done to make way for a future split of the API into implementation-specific assemblies.

As a result the following changes were made:

 * HttpCoordinateSystem.Category is now !CoordinateSystemCategory
 * HttpCoordinateSystem.CoordSys is now !CoordinateSystem
 * ICoordinateSystem is now ICoordinateSystemCatalog
 * The property ServerConnectionI.CoordinateSystem is now ServerConnectionI.CoordinateSystemCatalog
 * To create a blank coordinate system, use the new ICoordinateSystemCatalog.CreateEmptyCoordinateSystem() API

== New ServerConnectionI APIs ==

=== !SupportsResourcePreviews ===

This read-only property indicates whether Maestro is capable of resource previews. This returns true for !HttpServerConnection and false for !LocalNativeConnection.

=== !GetConnectionPropertyValues ===

Implemented in both HttpServerConnection and LocalNativeConnection

Description: Enumerates all known values for a given FDO connection property

Parameters:

 * providerName: The name of the FDO provider
 * propertyName: The name of the property to fetch values from
 * partialConnectionString: The current connection string, some providers require certain pieces of information in order to be able to enumerate the values of a property. For example, the MySQL provider's DataStore property requires being able to connect to the MySQL server first. Thus you would use the partial connection string to specify the MySQL service to connect to (eg. The partial connection string would look like:  Service=localhost:3306;Username=myuser;Password=mypassword)

Returns:

An array (string[]) of possible input values for the given property.

=== !ExecuteSqlQuery ===

Description: Executes a SQL SELECT query against a given feature source

Parameters:
 * featureSourceID: The feature source to query from
 * sql: The SQL SELECT statement

Returns:

A !FeatureSetReader containing the query result.

Notes:

Only SQL SELECT statements can be executed, non-query statements (eg. DELETE, UPDATE, INSERT, etc) are not supported. 

The !FeatureSetReader class has also been modified to accept MgSqlDataReader objects (from the native API) and XML output from a EXECUTESQL mapagent operation (from the Http API)

=== !ExecuteLoadProcedure ===

Implemented in !ServerConnectionBase, automatically inherited by !HttpServerConnection and !LocalNativeConnetion

Description: Executes the Load Procedure specified by the resource ID. If this load procedure has not been executed before, it will update the load procedure resource with the list of resource ids created. On subsequent executions, it will only create or update resources from this list.

Parameters:

 * resourceID: The resource ID of the Load Procedure
 * ignoreUnsupportedFeatures: If false, will throw an exception if the specified load procedure has features which are not supported for execution.
 * callback: An optional callback to indicate progress.

Returns:

 * An array of resource IDs that have been created or updated by the execution of this load procedure.

Notes:

The Load Procedure support in Maestro is very basic. The following load procedure types are supported:

 * SDF
 * SHP

The following Load Procedure types '''may be supported''' in future releases, if it is determined we can support these types with a portable implementation:

 * DWF
 * SQLite
 * Raster

The following Load Procedure types will '''NEVER''' be supported:
 
 * DWG

Of the supported load procedure types, the following features are not supported, and will throw an exception if ignoreUnsupportedFeatures = false

 * Generalization of data (will throw exception if value < 100%)
 * Convert to SDF (will throw exception if value = true)

Of the supported load procedure types, the following features are not supported. No exception is thrown regardless of the value of ignoreUnsupportedFeatures

 * SDF2 to SDF3 conversion (there's no pure .net way to detect if the input files are SDF2 files)
 * SDF duplicate record (there's no portable .net API available to inspect the contents of a local SDF file)

The general use case for Load Procedures is the quick and dirty loading of a group of SDF/SHP files into a given repository location, each referenced by a matching layer with default (monochromatic) styles. As long as you stick to this general usage scenario, the API will work as expected. These unsupported features are disabled on the user interface side.