= 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);
}}}

== New ServerConnectionI APIs ==

=== 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.