/// <summary>
 /// Constructs request to get shard with specific location for given shard map from GSM.
 /// </summary>
 /// <param name="shardMapManager">Shard map manager object.</param>
 /// <param name="operationName">Operation name, useful for diagnostics.</param>
 /// <param name="shardMap">Shard map for which shard is being requested.</param>
 /// <param name="location">Location of shard being searched.</param>
 internal FindShardByLocationGlobalOperation(ShardMapManager shardMapManager, string operationName, IStoreShardMap shardMap, ShardLocation location) :
     base(shardMapManager.Credentials, shardMapManager.RetryPolicy, operationName)
 {
     _shardMapManager = shardMapManager;
     _shardMap = shardMap;
     _location = location;
 }

        /// <summary>
        /// 建立 new shard, 或取得現有空的 shard (i.e. a shard 可能還沒 mapper ).
        /// 空的 shard 可能存在的原因是因為，創建和初始化的時候，我們無法 mapping 他
        /// </summary>
        private static Shard CreateOrGetEmptyShard(RangeShardMap<int> shardMap)
        {
            // 假如已經有了，則取得空的 shard
            Shard shard = FindEmptyShard(shardMap);
            if (shard == null)
            {
                // 為 Null，表示沒有空的，所以要建立

                // 更改 shard name
                string databaseName = string.Format(ShardNameFormat, shardMap.GetShards().Count());

                // 假如資料庫不存在，則建立資料庫
                // 假如存在，則會返回
                if (!SqlDatabaseUtils.DatabaseExists(Configuration.ShardMapManagerServerName, databaseName))
                {
                    SqlDatabaseUtils.CreateDatabase(Configuration.ShardMapManagerServerName, databaseName);
                }

                // 建立 schema 和相關的資料到 db
                // 並使用初始化腳本初始化，如果資料庫已經存在，會發生問題
                //
                SqlDatabaseUtils.ExecuteSqlScript(
                    Configuration.ShardMapManagerServerName, databaseName, InitializeShardScriptFile);

                // 產生shard Location ， 並取得 Shard
                ShardLocation shardLocation = new ShardLocation(Configuration.ShardMapManagerServerName, databaseName);
                shard = ShardManagementUtils.CreateOrGetShard(shardMap, shardLocation);
            }

            return shard;
        }

 /// <summary>
 /// Constructs request for obtaining all the shard maps and shards from an LSM.
 /// </summary>
 /// <param name="operationName">Operation name.</param>
 /// <param name="shardMapManager">Shard map manager.</param>
 /// <param name="location">Location of the LSM.</param>
 internal CheckShardLocalOperation(
     string operationName,
     ShardMapManager shardMapManager,
     ShardLocation location) :
     base(shardMapManager.Credentials, shardMapManager.RetryPolicy, location, operationName)
 {
 }

        // Enter a new shard - i.e. an empty database - to the shard map, allocate a first tenant to it 
        // and kick off EF intialization of the database to deploy schema
        // public void RegisterNewShard(string server, string database, string user, string pwd, string appname, int key)
        public void RegisterNewShard(string server, string database, string connstr, int key)
        {
            Shard shard;
            ShardLocation shardLocation = new ShardLocation(server, database);

            if (!this.ShardMap.TryGetShard(shardLocation, out shard))
            {
                shard = this.ShardMap.CreateShard(shardLocation);
            }

            SqlConnectionStringBuilder connStrBldr = new SqlConnectionStringBuilder(connstr);
            connStrBldr.DataSource = server;
            connStrBldr.InitialCatalog = database;

            // Go into a DbContext to trigger migrations and schema deployment for the new shard.
            // This requires an un-opened connection.
            using (var db = new ElasticScaleContext<int>(connStrBldr.ConnectionString))
            {
                // Run a query to engage EF migrations
                (from b in db.Blogs
                 select b).Count();
            }

            // Register the mapping of the tenant to the shard in the shard map.
            // After this step, DDR on the shard map can be used
            PointMapping<int> mapping;
            if (!this.ShardMap.TryGetMappingForKey(key, out mapping))
            {
                this.ShardMap.CreatePointMapping(key, shard);
            }
        }

        /// <summary>
        /// Creates a new shard, or gets an existing empty shard (i.e. a shard that has no mappings).
        /// The reason why an empty shard might exist is that it was created and initialized but we 
        /// failed to create a mapping to it.
        /// </summary>
        private static Shard CreateOrGetEmptyShard(RangeShardMap<int> shardMap)
        {
            // Get an empty shard if one already exists, otherwise create a new one
            Shard shard = FindEmptyShard(shardMap);
            if (shard == null)
            {
                // No empty shard exists, so create one

                // Choose the shard name
                string databaseName = string.Format(ShardNameFormat, shardMap.GetShards().Count());

                // Only create the database if it doesn't already exist. It might already exist if
                // we tried to create it previously but hit a transient fault.
                if (!SqlDatabaseUtils.DatabaseExists(Configuration.ShardMapManagerServerName, databaseName))
                {
                    SqlDatabaseUtils.CreateDatabase(Configuration.ShardMapManagerServerName, databaseName);
                }

                // Create schema and populate reference data on that database
                // The initialize script must be idempotent, in case it was already run on this database
                // and we failed to add it to the shard map previously
                SqlDatabaseUtils.ExecuteSqlScript(
                    Configuration.ShardMapManagerServerName, databaseName, InitializeShardScriptFile);

                // Add it to the shard map
                ShardLocation shardLocation = new ShardLocation(Configuration.ShardMapManagerServerName, databaseName);
                shard = ShardManagementUtils.CreateOrGetShard(shardMap, shardLocation);
            }

            return shard;
        }

 /// <summary>
 /// Constructs request to upgrade store hosting LSM.
 /// </summary>
 /// <param name="shardMapManager">Shard map manager object.</param>
 /// <param name="location">Store location to upgrade.</param>
 /// <param name="operationName">Operation name, useful for diagnostics.</param>
 /// <param name="targetVersion">Target version to upgrade.</param>
 internal UpgradeStoreLocalOperation(
     ShardMapManager shardMapManager,
     ShardLocation location,
     string operationName,
     Version targetVersion) :
     base(shardMapManager.Credentials, shardMapManager.RetryPolicy, location, operationName)
 {
     _targetVersion = targetVersion;
 }

        internal LabeledDbDataReader(MultiShardException exception, ShardLocation shardLocation, DbCommand cmd)
            : this(shardLocation, cmd)
        {
            if (null == exception)
            {
                throw new ArgumentNullException("exception");
            }

            this.Exception = exception;
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="MultiShardException"/> class with
        /// the specified shard location, error message and exception encountered.
        /// </summary>
        /// <param name="shardLocation"> specifies the location of the shard where the exception occurred.</param>
        /// <param name="message"> specifices the message that explains the reason for the exception.</param>
        /// <param name="inner"> specifies the exception encountered at the shard.</param>
        /// <exception cref="T:System.ArgumentNullException">The <paramref name="shardLocation"/> is null </exception>
        public MultiShardException(ShardLocation shardLocation, string message, Exception inner)
            : base(message, inner)
        {
            if (null == shardLocation)
            {
                throw new ArgumentNullException("shardLocation");
            }

            _shardLocation = shardLocation;
        }

 /// <summary>
 /// Constructs an instance of SqlOperationLocal.
 /// </summary>
 /// <param name="credentials">Credentials for connecting to SMM databases.</param>
 /// <param name="retryPolicy">Retry policy for requests.</param>
 /// <param name="location">Shard location where the operation is to be performed.</param>
 /// <param name="operationName">Operation name.</param>
 internal StoreOperationLocal(
     SqlShardMapManagerCredentials credentials,
     TransientFaultHandling.RetryPolicy retryPolicy,
     ShardLocation location,
     string operationName)
 {
     _credentials = credentials;
     _retryPolicy = retryPolicy;
     this.OperationName = operationName;
     this.Location = location;
 }

 /// <summary>
 /// Constructs request for Detaching the given shard and mapping information to the GSM database.
 /// </summary>
 /// <param name="shardMapManager">Shard map manager object.</param>
 /// <param name="operationName">Operation name.</param>
 /// <param name="location">Location to be detached.</param>
 /// <param name="shardMapName">Shard map from which shard is being detached.</param>
 /// <returns>The store operation.</returns>
 public virtual IStoreOperationGlobal CreateDetachShardGlobalOperation(
     ShardMapManager shardMapManager,
     string operationName,
     ShardLocation location,
     string shardMapName)
 {
     return new DetachShardGlobalOperation(
         shardMapManager,
         operationName,
         location,
         shardMapName);
 }

 /// <summary>
 /// Constructs the storage representation from client side objects.
 /// </summary>
 /// <param name="id">Shard Id.</param>
 /// <param name="version">Shard version.</param>
 /// <param name="shardMapId">Identify of shard map.</param>
 /// <param name="location">Data source location.</param>
 /// <param name="status">Status of the shard.</param>
 internal DefaultStoreShard(
     Guid id,
     Guid version,
     Guid shardMapId,
     ShardLocation location,
     int status)
 {
     this.Id = id;
     this.Version = version;
     this.ShardMapId = shardMapId;
     this.Location = location;
     this.Status = status;
 }

 /// <summary>
 /// Constructs request for replacing the LSM mappings for given shard map with the input mappings.
 /// </summary>
 /// <param name="shardMapManager">Shard map manager.</param>
 /// <param name="location">Location of the LSM.</param>
 /// <param name="operationName">Operation name.</param>
 /// <param name="shardMap">Local shard map.</param>
 /// <param name="shard">Local shard.</param>
 /// <param name="rangesToRemove">Optional list of ranges to minimize amount of deletions.</param>
 /// <param name="mappingsToAdd">List of mappings to add.</param>
 internal ReplaceMappingsLocalOperation(
     ShardMapManager shardMapManager,
     ShardLocation location,
     string operationName,
     IStoreShardMap shardMap,
     IStoreShard shard,
     IEnumerable<ShardRange> rangesToRemove,
     IEnumerable<IStoreMapping> mappingsToAdd) :
     base(shardMapManager.Credentials, shardMapManager.RetryPolicy, location, operationName)
 {
     _shardMap = shardMap;
     _shard = shard;
     _rangesToRemove = rangesToRemove;
     _mappingsToAdd = mappingsToAdd;
 }

        /// <summary>
        /// Constructs request for obtaining all the shard maps and shards from an LSM.
        /// </summary>
        /// <param name="shardMapManager">Shard map manager.</param>
        /// <param name="location">Location of the LSM.</param>
        /// <param name="operationName">Operation name.</param>
        /// <param name="shardMap">Local shard map.</param>
        /// <param name="shard">Local shard.</param>
        /// <param name="range">Optional range to get mappings from.</param>
        /// <param name="ignoreFailure">Ignore shard map not found error.</param>
        internal GetMappingsByRangeLocalOperation(
            ShardMapManager shardMapManager,
            ShardLocation location,
            string operationName,
            IStoreShardMap shardMap,
            IStoreShard shard,
            ShardRange range,
            bool ignoreFailure) :
            base(shardMapManager.Credentials, shardMapManager.RetryPolicy, location, operationName)
        {
            Debug.Assert(shard != null);

            _shardMap = shardMap;
            _shard = shard;
            _range = range;
            _ignoreFailure = ignoreFailure;
        }

        // Enter a new shard - i.e. an empty database - to the shard map, allocate a first tenant to it 
        public void RegisterNewShard(string server, string database, string connstr, int key)
        {
            Shard shard;
            ShardLocation shardLocation = new ShardLocation(server, database);

            if (!this.ShardMap.TryGetShard(shardLocation, out shard))
            {
                shard = this.ShardMap.CreateShard(shardLocation);
            }

            // Register the mapping of the tenant to the shard in the shard map.
            // After this step, DDR on the shard map can be used
            PointMapping<int> mapping;
            if (!this.ShardMap.TryGetMappingForKey(key, out mapping))
            {
                this.ShardMap.CreatePointMapping(key, shard);
            }
        }

        public void FailsValidationWhenAnyShardLocationsAreNull()
        {
            var sut = new AddInt32RangeMapShardsArgs
            {
                ConnectionString = @"Server = (localdb)\mssqllocaldb; Initial Catalog = SomeTestDb; Integrated Security = true; Application Name = Galen.CI.Azure.Sql.Sharding.App.Tests;",
                MapName = "MyTestIntRangeMapName",
                ShardLocations = new ShardLocations()
            };

            var validShardLocation = new ShardLocation
            {
                ServerName = @"(localdb)\.\SharedLocalDb",
                DatabaseName = "MyTestShardDb001"
            };

            sut.ShardLocations.Locations = new [] {validShardLocation, null};

            sut.Validate();
        }

 /// <summary>
 /// Request to get shard with specified location for a shard map from GSM.
 /// </summary>
 /// <param name="shardMap">Shard map for which to get shard.</param>
 /// <param name="location">Location for which to find shard.</param>
 /// <returns>Xml formatted request.</returns>
 internal static XElement FindShardByLocationGlobal(
     IStoreShardMap shardMap,
     ShardLocation location)
 {
     return new XElement(
         @"FindShardByLocationGlobal",
         StoreOperationRequestBuilder.s_gsmVersion,
         StoreObjectFormatterXml.WriteIStoreShardMap("ShardMap", shardMap),
         StoreObjectFormatterXml.WriteShardLocation("Location", location));
 }

 /// <summary>
 /// Returns the proper ShardManagementException corresponding to given error code in 
 /// <paramref name="result"/> for ShardMapper operations.
 /// </summary>
 /// <param name="result">Operation result object.</param>
 /// <param name="location">Location of LSM operation.</param>
 /// <param name="operationName">Operation being performed.</param>
 /// <param name="storedProcName">Stored procedure being executed.</param>
 /// <returns>ShardManagementException to be raised.</returns>
 internal static ShardManagementException OnShardMapperErrorLocal(
     IStoreResults result,
     ShardLocation location,
     string operationName,
     string storedProcName)
 {
     switch (result.Result)
     {
         case StoreResult.StoreVersionMismatch:
         case StoreResult.MissingParametersForStoredProcedure:
         default:
             return StoreOperationErrorHandler.OnCommonErrorLocal(
                 result,
                 location,
                 operationName,
                 storedProcName);
     }
 }

        /// <summary>
        /// Returns the proper ShardManagementException corresponding to given error code in 
        /// <paramref name="result"/> for ShardMap operations.
        /// </summary>
        /// <param name="result">Operation result object.</param>
        /// <param name="shardMap">Shard map object.</param>
        /// <param name="location">Location of operation.</param>
        /// <param name="errorCategory">Error category to use for raised errors.</param>
        /// <param name="operationName">Operation being performed.</param>
        /// <param name="storedProcName">Stored procedure being executed.</param>
        /// <returns>ShardManagementException to be raised.</returns>
        internal static ShardManagementException OnRecoveryErrorLocal(
            IStoreResults result,
            IStoreShardMap shardMap,
            ShardLocation location,
            ShardManagementErrorCategory errorCategory,
            string operationName,
            string storedProcName)
        {
            switch (result.Result)
            {
                case StoreResult.ShardMapDoesNotExist:
                    return new ShardManagementException(
                        errorCategory,
                        ShardManagementErrorCode.ShardMapDoesNotExist,
                        Errors._Store_ShardMap_DoesNotExistLocal,
                        shardMap.Name,
                        location,
                        storedProcName,
                        operationName);

                case StoreResult.StoreVersionMismatch:
                case StoreResult.MissingParametersForStoredProcedure:
                default:
                    return StoreOperationErrorHandler.OnCommonErrorLocal(
                        result,
                        location,
                        operationName,
                        storedProcName);
            }
        }

        /// <summary>
        /// Returns the proper ShardManagementException corresponding to given error code in 
        /// <paramref name="result"/> for ShardMap operations.
        /// </summary>
        /// <param name="result">Operation result object.</param>
        /// <param name="shardMap">Shard map object.</param>
        /// <param name="location">Location of LSM operation.</param>
        /// <param name="operationName">Operation being performed.</param>
        /// <param name="storedProcName">Stored procedure being executed.</param>
        /// <returns>ShardManagementException to be raised.</returns>
        internal static ShardManagementException OnValidationErrorLocal(
            IStoreResults result,
            IStoreShardMap shardMap,
            ShardLocation location,
            string operationName,
            string storedProcName)
        {
            switch (result.Result)
            {
                case StoreResult.ShardMapDoesNotExist:
                    return new ShardManagementException(
                        ShardManagementErrorCategory.Validation,
                        ShardManagementErrorCode.ShardMapDoesNotExist,
                        Errors._Store_Validate_ShardMapDoesNotExist,
                        shardMap.Name,
                        location,
                        operationName,
                        storedProcName);

                case StoreResult.ShardDoesNotExist:
                    return new ShardManagementException(
                        ShardManagementErrorCategory.Validation,
                        ShardManagementErrorCode.ShardDoesNotExist,
                        Errors._Store_Validate_ShardDoesNotExist,
                        location,
                        shardMap.Name,
                        operationName,
                        storedProcName);

                case StoreResult.ShardVersionMismatch:
                    return new ShardManagementException(
                        ShardManagementErrorCategory.Validation,
                        ShardManagementErrorCode.ShardVersionMismatch,
                        Errors._Store_Validate_ShardVersionMismatch,
                        location,
                        shardMap.Name,
                        operationName,
                        storedProcName);

                case StoreResult.MappingDoesNotExist:
                    return new ShardManagementException(
                        ShardManagementErrorCategory.Validation,
                        ShardManagementErrorCode.MappingDoesNotExist,
                        Errors._Store_Validate_MappingDoesNotExist,
                        location,
                        shardMap.Name,
                        operationName,
                        storedProcName);

                case StoreResult.MappingIsOffline:
                    return new ShardManagementException(
                        ShardManagementErrorCategory.Validation,
                        ShardManagementErrorCode.MappingIsOffline,
                        Errors._Store_Validate_MappingIsOffline,
                        location,
                        shardMap.Name,
                        operationName,
                        storedProcName);

                case StoreResult.StoreVersionMismatch:
                case StoreResult.MissingParametersForStoredProcedure:
                default:
                    return StoreOperationErrorHandler.OnCommonErrorLocal(
                        result,
                        location,
                        operationName,
                        storedProcName);
            }
        }

 /// <summary>
 /// Constructs a request to upgrade store location.
 /// </summary>
 /// <param name="shardMapManager">Shard map manager object.</param>
 /// <param name="location">Location to upgrade.</param>
 /// <param name="operationName">Operation name, useful for diagnostics.</param>
 /// <param name="targetVersion">Target version of store to deploy.</param>
 /// <returns>The store operation.</returns>
 public virtual IStoreOperationLocal CreateUpgradeStoreLocalOperation(
     ShardMapManager shardMapManager,
     ShardLocation location,
     string operationName,
     Version targetVersion)
 {
     return new UpgradeStoreLocalOperation(
         shardMapManager,
         location,
         operationName,
         targetVersion);
 }