Add preliminary support for the Cloud Files Extract Archive operation (fixes #218)

Author: sharwell

src/corelib/Providers/Rackspace/CloudFilesProvider.cs

@@ -20,6 +20,7 @@
 using net.openstack.Providers.Rackspace.Objects.Mapping;
 using net.openstack.Providers.Rackspace.Objects.Response;
 using net.openstack.Providers.Rackspace.Validators;
+using Newtonsoft.Json;
 
 namespace net.openstack.Providers.Rackspace
 {
@@ -1279,6 +1280,146 @@ public void BulkDelete(IEnumerable<KeyValuePair<string, string>> items, Dictiona
             }
         }
 
+        /// <summary>
+        /// Upload and automatically extract an archive of files.
+        /// </summary>
+        /// <param name="filePath">The source file path. Example <localUri>c:\folder1\folder2\archive_name.tar.gz</localUri></param>
+        /// <param name="uploadPath">The target path for the extracted files. For details about this value, see the Extract Archive reference link in the documentation for this method.</param>
+        /// <param name="archiveFormat">The archive format.</param>
+        /// <param name="contentType">The content type of the files extracted from the archive. If the value is <c>null</c> or empty, the content type of the extracted files is unspecified.</param>
+        /// <param name="chunkSize">The buffer size to use for copying streaming data.</param>
+        /// <param name="headers">A collection of custom HTTP headers to associate with the object (see <see cref="GetObjectHeaders"/>).</param>
+        /// <param name="region">The region in which to execute this action. If not specified, the user's default region will be used.</param>
+        /// <param name="progressUpdated">A callback for progress updates. If the value is <c>null</c>, no progress updates are reported.</param>
+        /// <param name="useInternalUrl"><c>true</c> to use the endpoint's <see cref="Endpoint.InternalURL"/>; otherwise <c>false</c> to use the endpoint's <see cref="Endpoint.PublicURL"/>.</param>
+        /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
+        /// <returns>An <see cref="ExtractArchiveResponse"/> object containing the detailed result of the extract archive operation.</returns>
+        /// <exception cref="ArgumentNullException">
+        /// If <paramref name="filePath"/> is <c>null</c>.
+        /// <para>-or-</para>
+        /// <para>If <paramref name="uploadPath"/> is <c>null</c>.</para>
+        /// <para>-or-</para>
+        /// <para>If <paramref name="archiveFormat"/> is <c>null</c>.</para>
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        /// If <paramref name="filePath"/> is empty.
+        /// <para>-or-</para>
+        /// <para>If <paramref name="headers"/> contains two equivalent keys when compared using <see cref="StringComparer.OrdinalIgnoreCase"/>.</para>
+        /// </exception>
+        /// <exception cref="ArgumentOutOfRangeException">If <paramref name="chunkSize"/> is less than 0.</exception>
+        /// <exception cref="FileNotFoundException">If the file <paramref name="filePath"/> could not be found.</exception>
+        /// <exception cref="NotSupportedException">
+        /// If the provider does not support the given <paramref name="identity"/> type.
+        /// <para>-or-</para>
+        /// <para>The specified <paramref name="archiveFormat"/> is not supported by the provider.</para>
+        /// <para>-or-</para>
+        /// <para>The specified <paramref name="region"/> is not supported.</para>
+        /// <para>-or-</para>
+        /// <para><paramref name="useInternalUrl"/> is <c>true</c> and the provider does not support internal URLs.</para>
+        /// </exception>
+        /// <exception cref="InvalidOperationException">
+        /// If <paramref name="identity"/> is <c>null</c> and no default identity is available for the provider.
+        /// <para>-or-</para>
+        /// <para>If <paramref name="region"/> is <c>null</c> and no default region is available for the provider.</para>
+        /// </exception>
+        /// <exception cref="ResponseException">If the REST API request failed.</exception>
+        /// <seealso href="http://docs.rackspace.com/files/api/v1/cf-devguide/content/Extract_Archive-d1e2338.html">Extract Archive (Rackspace Cloud Files Developer Guide - API v1)</seealso>
+        /// <preliminary/>
+        public ExtractArchiveResponse ExtractArchiveFromFile(string filePath, string uploadPath, ArchiveFormat archiveFormat, string contentType = null, int chunkSize = 4096, Dictionary<string, string> headers = null, string region = null, Action<long> progressUpdated = null, bool useInternalUrl = false, CloudIdentity identity = null)
+        {
+            if (filePath == null)
+                throw new ArgumentNullException("filePath");
+            if (uploadPath == null)
+                throw new ArgumentNullException("uploadPath");
+            if (archiveFormat == null)
+                throw new ArgumentNullException("archiveFormat");
+            if (string.IsNullOrEmpty(filePath))
+                throw new ArgumentException("filePath cannot be empty");
+            if (chunkSize < 0)
+                throw new ArgumentOutOfRangeException("chunkSize");
+            CheckIdentity(identity);
+
+            using (var stream = File.OpenRead(filePath))
+            {
+                return ExtractArchive(stream, uploadPath, archiveFormat, contentType, chunkSize, headers, region, progressUpdated, useInternalUrl, identity);
+            }
+        }
+
+        /// <summary>
+        /// Upload and automatically extract an archive of files.
+        /// </summary>
+        /// <param name="stream">A <see cref="Stream"/> providing the data for the archive.</param>
+        /// <param name="uploadPath">The target path for the extracted files. For details about this value, see the Extract Archive reference link in the documentation for this method.</param>
+        /// <param name="archiveFormat">The archive format.</param>
+        /// <param name="contentType">The content type of the files extracted from the archive. If the value is <c>null</c> or empty, the content type of the extracted files is unspecified.</param>
+        /// <param name="chunkSize">The buffer size to use for copying streaming data.</param>
+        /// <param name="headers">A collection of custom HTTP headers to associate with the object (see <see cref="GetObjectHeaders"/>).</param>
+        /// <param name="region">The region in which to execute this action. If not specified, the user's default region will be used.</param>
+        /// <param name="progressUpdated">A callback for progress updates. If the value is <c>null</c>, no progress updates are reported.</param>
+        /// <param name="useInternalUrl"><c>true</c> to use the endpoint's <see cref="Endpoint.InternalURL"/>; otherwise <c>false</c> to use the endpoint's <see cref="Endpoint.PublicURL"/>.</param>
+        /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
+        /// <returns>An <see cref="ExtractArchiveResponse"/> object containing the detailed result of the extract archive operation.</returns>
+        /// <exception cref="ArgumentNullException">
+        /// If <paramref name="stream"/> is <c>null</c>.
+        /// <para>-or-</para>
+        /// <para>If <paramref name="uploadPath"/> is <c>null</c>.</para>
+        /// <para>-or-</para>
+        /// <para>If <paramref name="archiveFormat"/> is <c>null</c>.</para>
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        /// If <paramref name="headers"/> contains two equivalent keys when compared using <see cref="StringComparer.OrdinalIgnoreCase"/>.
+        /// </exception>
+        /// <exception cref="ArgumentOutOfRangeException">If <paramref name="chunkSize"/> is less than 0.</exception>
+        /// <exception cref="NotSupportedException">
+        /// If the provider does not support the given <paramref name="identity"/> type.
+        /// <para>-or-</para>
+        /// <para>The specified <paramref name="archiveFormat"/> is not supported by the provider.</para>
+        /// <para>-or-</para>
+        /// <para>The specified <paramref name="region"/> is not supported.</para>
+        /// <para>-or-</para>
+        /// <para><paramref name="useInternalUrl"/> is <c>true</c> and the provider does not support internal URLs.</para>
+        /// </exception>
+        /// <exception cref="InvalidOperationException">
+        /// If <paramref name="identity"/> is <c>null</c> and no default identity is available for the provider.
+        /// <para>-or-</para>
+        /// <para>If <paramref name="region"/> is <c>null</c> and no default region is available for the provider.</para>
+        /// </exception>
+        /// <exception cref="ResponseException">If the REST API request failed.</exception>
+        /// <seealso href="http://docs.rackspace.com/files/api/v1/cf-devguide/content/Extract_Archive-d1e2338.html">Extract Archive (Rackspace Cloud Files Developer Guide - API v1)</seealso>
+        /// <preliminary/>
+        public ExtractArchiveResponse ExtractArchive(Stream stream, string uploadPath, ArchiveFormat archiveFormat, string contentType = null, int chunkSize = 4096, Dictionary<string, string> headers = null, string region = null, Action<long> progressUpdated = null, bool useInternalUrl = false, CloudIdentity identity = null)
+        {
+            if (stream == null)
+                throw new ArgumentNullException("stream");
+            if (uploadPath == null)
+                throw new ArgumentNullException("uploadPath");
+            if (archiveFormat == null)
+                throw new ArgumentNullException("archiveFormat");
+            if (chunkSize < 0)
+                throw new ArgumentOutOfRangeException("chunkSize");
+            CheckIdentity(identity);
+
+            UriTemplate template;
+            if (!string.IsNullOrEmpty(uploadPath))
+                template = new UriTemplate("{uploadPath}?extract-archive={archiveFormat}");
+            else
+                template = new UriTemplate("?extract-archive={archiveFormat}");
+
+            Uri baseAddress = new Uri(GetServiceEndpointCloudFiles(identity, region, useInternalUrl));
+            Dictionary<string, string> parameters = new Dictionary<string, string> { { "archiveFormat", archiveFormat.ToString() } };
+            if (!string.IsNullOrEmpty(uploadPath))
+                parameters.Add("uploadPath", uploadPath);
+
+            Uri urlPath = template.BindByName(baseAddress, parameters);
+
+            RequestSettings settings = BuildDefaultRequestSettings();
+            settings.ChunkRequest = true;
+            settings.ContentType = contentType;
+
+            Response response = StreamRESTRequest(identity, urlPath, HttpMethod.PUT, stream, chunkSize, headers: headers, progressUpdated: progressUpdated, requestSettings: settings);
+            return JsonConvert.DeserializeObject<ExtractArchiveResponse>(response.RawBody);
+        }
+
         /// <inheritdoc />
         public void MoveObject(string sourceContainer, string sourceObjectName, string destinationContainer, string destinationObjectName, string destinationContentType = null, Dictionary<string, string> headers = null, string region = null, bool useInternalUrl = false, CloudIdentity identity = null)
         {

src/corelib/Providers/Rackspace/Objects/ArchiveFormat.cs

@@ -0,0 +1,101 @@
+namespace net.openstack.Providers.Rackspace.Objects
+{
+    using System;
+    using System.Collections.Concurrent;
+    using net.openstack.Core;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// Represents a archive format for the Cloud Files Extract Archive operation.
+    /// </summary>
+    /// <remarks>
+    /// This class functions as a strongly-typed enumeration of known archive types,
+    /// with added support for unknown types returned or supported by a server extension.
+    /// </remarks>
+    /// <seealso cref="CloudFilesProvider.ExtractArchive"/>
+    /// <seealso cref="CloudFilesProvider.ExtractArchiveFromFile"/>
+    /// <threadsafety static="true" instance="false"/>
+    /// <preliminary/>
+    [JsonConverter(typeof(ArchiveFormat.Converter))]
+    public sealed class ArchiveFormat : ExtensibleEnum<ArchiveFormat>
+    {
+        private static readonly ConcurrentDictionary<string, ArchiveFormat> _types =
+            new ConcurrentDictionary<string, ArchiveFormat>(StringComparer.OrdinalIgnoreCase);
+        private static readonly ArchiveFormat _tar = FromName("tar");
+        private static readonly ArchiveFormat _tarGz = FromName("tar.gz");
+        private static readonly ArchiveFormat _tarBz2 = FromName("tar.bz2");
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ArchiveFormat"/> class with the specified name.
+        /// </summary>
+        /// <inheritdoc/>
+        private ArchiveFormat(string name)
+            : base(name)
+        {
+        }
+
+        /// <summary>
+        /// Gets the <see cref="ArchiveFormat"/> instance with the specified name.
+        /// </summary>
+        /// <param name="name">The name.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="name"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="name"/> is empty.</exception>
+        public static ArchiveFormat FromName(string name)
+        {
+            if (name == null)
+                throw new ArgumentNullException("name");
+            if (string.IsNullOrEmpty(name))
+                throw new ArgumentException("name cannot be empty");
+
+            return _types.GetOrAdd(name, i => new ArchiveFormat(i));
+        }
+
+        /// <summary>
+        /// Gets an <see cref="ArchiveFormat"/> representing <c>tar</c> files.
+        /// </summary>
+        public static ArchiveFormat Tar
+        {
+            get
+            {
+                return _tar;
+            }
+        }
+
+        /// <summary>
+        /// Gets an <see cref="ArchiveFormat"/> representing <c>tar.gz</c> files.
+        /// </summary>
+        public static ArchiveFormat TarGz
+        {
+            get
+            {
+                return _tarGz;
+            }
+        }
+
+        /// <summary>
+        /// Gets an <see cref="ArchiveFormat"/> representing <c>tar.bz2</c> files.
+        /// </summary>
+        public static ArchiveFormat TarBz2
+        {
+            get
+            {
+                return _tarBz2;
+            }
+        }
+
+        /// <summary>
+        /// Provides support for serializing and deserializing <see cref="ArchiveFormat"/>
+        /// objects to JSON string values.
+        /// </summary>
+        /// <threadsafety static="true" instance="false"/>
+        /// <preliminary/>
+        private sealed class Converter : ConverterBase
+        {
+            /// <inheritdoc/>
+            protected override ArchiveFormat FromName(string name)
+            {
+                return ArchiveFormat.FromName(name);
+            }
+        }
+    }
+}

src/corelib/Providers/Rackspace/Objects/Response/ExtractArchiveError.cs

@@ -0,0 +1,65 @@
+namespace net.openstack.Providers.Rackspace.Objects.Response
+{
+    using System;
+
+    /// <summary>
+    /// Represents an error which occurred while extracting a file during an Extract Archive operation.
+    /// </summary>
+    /// <seealso cref="CloudFilesProvider.ExtractArchive"/>
+    /// <seealso cref="CloudFilesProvider.ExtractArchiveFromFile"/>
+    /// <threadsafety static="true" instance="false"/>
+    /// <preliminary/>
+    public class ExtractArchiveError
+    {
+        /// <summary>
+        /// This is the backing field for the <see cref="Path"/> property.
+        /// </summary>
+        private readonly string _path;
+
+        /// <summary>
+        /// This is the backing field for the <see cref="Status"/> property.
+        /// </summary>
+        private readonly string _status;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ExtractArchiveError"/> class
+        /// with the specified path and status.
+        /// </summary>
+        /// <param name="path">The path of the file affected by this error.</param>
+        /// <param name="status">The specific status for the error affecting the file.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="path"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="path"/> is empty.</exception>
+        public ExtractArchiveError(string path, string status)
+        {
+            if (path == null)
+                throw new ArgumentNullException("path");
+            if (string.IsNullOrEmpty(path))
+                throw new ArgumentException("path cannot be empty");
+
+            _path = path;
+            _status = status;
+        }
+
+        /// <summary>
+        /// Gets the path of the file affected by this error.
+        /// </summary>
+        public string Path
+        {
+            get
+            {
+                return _path;
+            }
+        }
+
+        /// <summary>
+        /// Gets the specific status for the error affecting the file.
+        /// </summary>
+        public string Status
+        {
+            get
+            {
+                return _status;
+            }
+        }
+    }
+}