Add examples for IObjectStorageProvider.ListObject (fixes #323)

Author: sharwell

src/Samples/CPPCodeSamples/CPPCodeSamples.vcxproj

@@ -85,6 +85,7 @@
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="AssemblyInfo.cpp" />
+    <ClCompile Include="ObjectStorageProviderExamples.cpp" />
     <ClCompile Include="QueueingServiceExamples.cpp" />
     <ClCompile Include="Stdafx.cpp">
       <PrecompiledHeader Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">Create</PrecompiledHeader>

src/Samples/CPPCodeSamples/CPPCodeSamples.vcxproj.filters

@@ -32,6 +32,9 @@
     <ClCompile Include="QueueingServiceExamples.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="ObjectStorageProviderExamples.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <Text Include="ReadMe.txt" />

src/Samples/CPPCodeSamples/ObjectStorageProviderExamples.cpp

@@ -0,0 +1,55 @@
+#include "Stdafx.h"
+
+using namespace net::openstack::Core;
+using namespace net::openstack::Core::Domain;
+using namespace net::openstack::Core::Providers;
+using namespace System;
+using namespace System::Collections::Generic;
+
+ref class ObjectStorageProviderExamples
+{
+public:
+#pragma region ListObjectsInContainer
+	void ListObjects(IObjectStorageProvider^ provider, String^ containerName)
+	{
+		Console::WriteLine("Objects in container {0}", containerName);
+		for each (ContainerObject^ containerObject in ListAllObjects(provider, containerName))
+			Console::WriteLine("    {0}", containerObject->Name);
+	}
+
+	static IEnumerable<ContainerObject^>^ ListAllObjects(IObjectStorageProvider^ provider, String^ containerName)
+	{
+		return ListAllObjects(provider, containerName, Nullable<int>(), nullptr, nullptr, false, nullptr);
+	}
+
+	static IEnumerable<ContainerObject^>^ ListAllObjects(
+		IObjectStorageProvider^ provider,
+		String^ containerName,
+		Nullable<int> blockSize,
+		String^ prefix,
+		String^ region,
+		bool useInternalUrl,
+		CloudIdentity^ identity)
+	{
+		if (blockSize.HasValue && blockSize.Value <= 0)
+			throw gcnew ArgumentOutOfRangeException("blockSize");
+
+		List<ContainerObject^>^ result = gcnew List<ContainerObject^>();
+		ContainerObject^ lastContainerObject = nullptr;
+		do
+		{
+			String^ marker = lastContainerObject ? lastContainerObject->Name : nullptr;
+			IEnumerable<ContainerObject^>^ containerObjects =
+				provider->ListObjects(containerName, blockSize, marker, nullptr, prefix, region, useInternalUrl, identity);
+			int previousCount = result->Count;
+			result->AddRange(containerObjects);
+			if (result->Count > previousCount)
+				lastContainerObject = result[result->Count - 1];
+			else
+				lastContainerObject = nullptr;
+		} while (lastContainerObject);
+
+		return result;
+	}
+#pragma endregion
+};

src/Samples/CSharpCodeSamples/CSharpCodeSamples.csproj

@@ -42,6 +42,7 @@
     <Reference Include="System.Xml" />
   </ItemGroup>
   <ItemGroup>
+    <Compile Include="ObjectStorageProviderExamples.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="QueueingServiceExamples.cs" />
   </ItemGroup>

src/Samples/CSharpCodeSamples/ObjectStorageProviderExamples.cs

@@ -0,0 +1,47 @@
+namespace CSharpCodeSamples
+{
+    using System;
+    using System.Collections.Generic;
+    using net.openstack.Core.Domain;
+    using net.openstack.Core.Providers;
+
+    public class ObjectStorageProviderExamples
+    {
+        #region ListObjectsInContainer
+        public void ListObjects(IObjectStorageProvider provider, string containerName)
+        {
+            Console.WriteLine("Objects in container {0}", containerName);
+            foreach (ContainerObject containerObject in ListAllObjects(provider, containerName))
+                Console.WriteLine("    {0}", containerObject.Name);
+        }
+
+        private static IEnumerable<ContainerObject> ListAllObjects(
+            IObjectStorageProvider provider,
+            string containerName,
+            int? blockSize = null,
+            string prefix = null,
+            string region = null,
+            bool useInternalUrl = false,
+            CloudIdentity identity = null)
+        {
+            if (blockSize <= 0)
+                throw new ArgumentOutOfRangeException("blockSize");
+
+            ContainerObject lastContainerObject = null;
+
+            do
+            {
+                string marker = lastContainerObject != null ? lastContainerObject.Name : null;
+                IEnumerable<ContainerObject> containerObjects =
+                    provider.ListObjects(containerName, blockSize, marker, null, prefix, region, useInternalUrl, identity);
+                lastContainerObject = null;
+                foreach (ContainerObject containerObject in containerObjects)
+                {
+                    lastContainerObject = containerObject;
+                    yield return containerObject;
+                }
+            } while (lastContainerObject != null);
+        }
+        #endregion ListObjectsInContainer
+    }
+}

src/Samples/FSharpCodeSamples/FSharpCodeSamples.fsproj

@@ -53,6 +53,7 @@
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="QueueingServiceExamples.fs" />
+    <Compile Include="ObjectStorageProviderExamples.fs" />
   </ItemGroup>
   <Choose>
     <When Condition="'$(VisualStudioVersion)' == '11.0'">

src/Samples/FSharpCodeSamples/ObjectStorageProviderExamples.fs

@@ -0,0 +1,29 @@
+module ObjectStorageProviderExamples
+
+open System;
+open System.Collections.Generic;
+open net.openstack.Core.Domain;
+open net.openstack.Core.Providers;
+
+//#region ListObjectsInContainer
+let listAllObjects(provider : IObjectStorageProvider, containerName : string) =
+    seq {
+        let lastContainerObject : ContainerObject ref = { contents = null }
+        let finished : bool ref = { contents = false }
+        while not !finished do
+            let marker = if !lastContainerObject <> null then (!lastContainerObject).Name else null
+            let containerObjects = provider.ListObjects(containerName, marker= marker)
+            lastContainerObject := null
+            for containerObject in containerObjects do
+                lastContainerObject := containerObject
+                yield containerObject
+            if !lastContainerObject = null then
+                finished := true
+    }
+
+let listObjects(provider : IObjectStorageProvider, containerName : string) =
+    Console.WriteLine("Objects in container {0}", containerName)
+    for containerObject in listAllObjects(provider, containerName) do
+        Console.WriteLine("    {0}", containerObject.Name)
+    ()
+//#endregion

src/Samples/VBCodeSamples/ObjectStorageProviderExamples.vb

@@ -0,0 +1,41 @@
+Imports net.openstack.Core.Providers
+Imports net.openstack.Core.Domain
+
+Public Class ObjectStorageProviderExamples
+
+#Region "ListObjectsInContainer"
+    Public Sub ListObjects(provider As IObjectStorageProvider, containerName As String)
+        Console.WriteLine("Objects in container {0}", containerName)
+        For Each containerObject In ListAllObjects(provider, containerName)
+            Console.WriteLine("    {0}", containerObject.Name)
+        Next
+    End Sub
+
+    Private Shared Iterator Function ListAllObjects(
+        provider As IObjectStorageProvider,
+        containerName As String,
+        Optional blockSize As Nullable(Of Integer) = Nothing,
+        Optional prefix As String = Nothing,
+        Optional region As String = Nothing,
+        Optional useInternalUrl As Boolean = False,
+        Optional identity As CloudIdentity = Nothing) As IEnumerable(Of ContainerObject)
+
+        If blockSize <= 0 Then
+            Throw New ArgumentOutOfRangeException("blockSize")
+        End If
+
+        Dim lastContainerObject As ContainerObject = Nothing
+        Do
+            Dim marker = If(lastContainerObject IsNot Nothing, lastContainerObject.Name, Nothing)
+            Dim containerObjects = provider.ListObjects(containerName, blockSize, marker, Nothing, prefix, region, useInternalUrl, identity)
+            lastContainerObject = Nothing
+            For Each containerObject In containerObjects
+                lastContainerObject = containerObject
+                Yield containerObject
+            Next
+        Loop While lastContainerObject IsNot Nothing
+    End Function
+#End Region
+
+
+End Class

src/Samples/VBCodeSamples/VBCodeSamples.vbproj

@@ -79,6 +79,7 @@
       <DependentUpon>Settings.settings</DependentUpon>
       <DesignTimeSharedInput>True</DesignTimeSharedInput>
     </Compile>
+    <Compile Include="ObjectStorageProviderExamples.vb" />
     <Compile Include="QueueingServiceExamples.vb" />
   </ItemGroup>
   <ItemGroup>

src/corelib/Core/Providers/IObjectStorageProvider.cs

@@ -1038,6 +1038,15 @@ public interface IObjectStorageProvider
         /// <para>If <paramref name="region"/> is <see langword="null"/> and no default region is available for the provider.</para>
         /// </exception>
         /// <exception cref="ResponseException">If the REST API request failed.</exception>
+        /// <example>
+        /// <para>The following example demonstrates the use of this method to output the names of all objects in a container
+        /// using <see cref="Console.WriteLine(string, object[])"/>. In the example, the pagination details of this method are handled by the
+        /// helper method <c>ListAllObjects</c>.</para>
+        /// <code source="..\Samples\CSharpCodeSamples\ObjectStorageProviderExamples.cs" region="ListObjectsInContainer" language="cs"/>
+        /// <code source="..\Samples\VBCodeSamples\ObjectStorageProviderExamples.vb" region="ListObjectsInContainer" language="vbnet"/>
+        /// <code source="..\Samples\CPPCodeSamples\ObjectStorageProviderExamples.cpp" region="ListObjectsInContainer" language="cpp"/>
+        /// <code source="..\Samples\FSharpCodeSamples\ObjectStorageProviderExamples.fs" region="ListObjectsInContainer" language="fs"/>
+        /// </example>
         /// <seealso href="http://docs.openstack.org/api/openstack-object-storage/1.0/content/list-objects.html">List Objects (OpenStack Object Storage API v1 Reference)</seealso>
         IEnumerable<ContainerObject> ListObjects(string container, int? limit = null, string marker = null, string markerEnd = null, string prefix = null, string region = null, bool useInternalUrl = false, CloudIdentity identity = null);