/// <summary>
        /// The action invoked when a <see cref="Borrowed<T>"/> is being returned.
        /// </summary>
        /// <param name="guild">The guild that's being returned. May be null if the guild borrowed is null.</param>
        /// <param name="data">
        /// The object placed into the data field at the construction of the <see cref="Borrowed<T>"/>.
        /// </param>
        /// <param name="commit">
        /// True if the user wanted to commit the changes, false if they wanted them discarded.
        /// </param>
        private static void ReturnGuild(Guild guild, object data, bool commit)
        {
            var sourceStream = (FileStream)data;

            if (commit)
            {
                sourceStream.Seek(0, SeekOrigin.Begin);
                sourceStream.SetLength(0);

                Formatting formatting;
                #if DEBUG
                formatting = Formatting.Indented;
                #else
                formatting = Formatting.None;
                #endif

                // TODO: In theory, we shouldn't need to copy to a string, and then serialize to file.
                //   Figure out how to serialize directly to file.
                var content = JsonConvert.SerializeObject(
                    GuildConverter.ToJToken(guild),
                    formatting);

                var writer = new StreamWriter(sourceStream);
                writer.Write(content);
                writer.Flush();
            }

            sourceStream.Dispose();
        }
        /// <summary>
        /// Checkout out a <see cref="Guild"/>.
        /// </summary>
        /// <param name="guildId">An id representing a guild.</param>
        /// <param name="recycleResult">A preallocated result that should be returned if passed in.</param>
        /// <returns>The borrowed guild.</returns>
        public async Task <GuildCheckoutResult> Checkout(Snowflake guildId, GuildCheckoutResult recycleResult = null)
        {
            var retVal = recycleResult ?? new GuildCheckoutResult();

            try
            {
                string blobName   = AzureBlobGuildRepository.GetBlobName(guildId);
                var    blobClient = this.blobContainerClient.GetBlockBlobClient(blobName);

                // Aquire a lease on the blob
                var blobLeaseClient = blobClient.GetBlobLeaseClient();
                var leaseResult     = await blobLeaseClient.AcquireAsync(AzureBlobGuildRepository.BlobLeaseDuration).ConfigureAwait(false);

                var lease = leaseResult.Value;

                Guild guild;
                using (var sourceStream = await blobClient.OpenReadAsync())
                    using (var streamReader = new StreamReader(sourceStream))
                        using (var jsonReader = new JsonTextReader(streamReader))
                        {
                            guild = GuildConverter.FromJToken(guildId, await JObject.ReadFromAsync(jsonReader));
                        }

                retVal.ToSuccess(new Borrowed <Guild>(
                                     isntance: guild,
                                     data: lease,
                                     onReturn: this.ReturnGuild));

                return(retVal);
            }
            catch (RequestFailedException e)
            {
                if (e.Status == AzureBlobGuildRepository.NotFoundStatus)
                {
                    retVal.ToDoesNotExist();
                    return(retVal);
                }
                else if (e.Status == AzureBlobGuildRepository.ConflictStatus && "LeaseAlreadyPresent".Equals(e.ErrorCode, StringComparison.OrdinalIgnoreCase))
                {
                    retVal.ToLocked();
                    return(retVal);
                }
                else
                {
                    throw;
                }
            }
        }
        /// <summary>
        /// Checkout out or create a <see cref="Guild"/> if one does not exist.
        /// </summary>
        /// <param name="guildId">An id representing a guild.</param>
        /// <param name="recycleResult">A preallocated result that should be returned if passed in.</param>
        /// <returns>The borrowed guild.</returns>
        public async Task <GuildCheckoutResult> Checkout(Snowflake guildId, GuildCheckoutResult recycleResult = null)
        {
            var retVal = recycleResult ?? new GuildCheckoutResult();

            try
            {
                var sourceStream = new FileStream(
                    FileBasedGuildRepository.GetFilePath(guildId),
                    FileMode.Open,
                    FileAccess.ReadWrite,
                    FileShare.None,
                    bufferSize: 4096,
                    useAsync: true);

                var streamReader = new StreamReader(sourceStream);
                var jsonReader   = new JsonTextReader(streamReader);
                var guild        = GuildConverter.FromJToken(guildId, await JObject.ReadFromAsync(jsonReader));

                retVal.ToSuccess(new Borrowed <Guild>(
                                     isntance: guild,
                                     data: sourceStream,
                                     onReturn: FileBasedGuildRepository.ReturnGuild));
                return(retVal);
            }
            catch (FileNotFoundException)
            {
                retVal.ToDoesNotExist();
                return(retVal);
            }
            catch (IOException e)
            {
                if (e.HResult == FileBasedGuildRepository.LockedFileHRResult)
                {
                    retVal.ToLocked();
                    return(retVal);
                }
                else
                {
                    throw;
                }
            }
        }
        /// <summary>
        /// The action invoked when a <see cref="Borrowed<T>"/> is being returned.
        /// </summary>
        /// <param name="guild">The guild that's being returned.</param>
        /// <param name="data">
        /// The object placed into the data field at the construction of the <see cref="Borrowed<T>"/>.
        /// </param>
        /// <param name="commit">
        /// True if the user wanted to commit the changes, false if they wanted them discarded.
        /// </param>
        private void ReturnGuild(Guild guild, object data, bool commit)
        {
            string blobName = AzureBlobGuildRepository.GetBlobName(guild.Id);

            var blobLease  = (BlobLease)data;
            var blobClient = this.blobContainerClient.GetBlockBlobClient(blobName);

            // Get the lease client and populate the lease information in the request options
            var blobLeaseClient       = blobClient.GetBlobLeaseClient(blobLease.LeaseId);
            var blobRequestConditions = new BlobRequestConditions()
            {
                LeaseId = blobLeaseClient.LeaseId
            };

            if (commit)
            {
                JsonSerializer serializer = new JsonSerializer();
#if DEBUG
                serializer.Formatting = Formatting.Indented;
#else
                serializer.Formatting = Formatting.None;
#endif

                using (var stream = blobClient.OpenWrite(overwrite: true, new BlockBlobOpenWriteOptions()
                {
                    OpenConditions = blobRequestConditions
                }))
                    using (var streamWriter = new StreamWriter(stream))
                        using (var writer = new JsonTextWriter(streamWriter))
                        {
                            serializer.Serialize(writer, GuildConverter.ToJToken(guild));
                        }
            }

            // Release the lease on the blob
            blobLeaseClient.Release();
        }