Skip to content

Commit 6c836a0

Browse files
sharwellsharwell
committed
Updated documentation showing the creation of objects with metadata (fixes #340)
1 parent 6615ffc commit 6c836a0

3 files changed

Lines changed: 81 additions & 3 deletions

File tree

‎src/Samples/CSharpCodeSamples/ObjectStorageProviderExamples.cs‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
using System.Collections.Generic;
55
using net.openstack.Core.Domain;
66
using net.openstack.Core.Providers;
7+
using net.openstack.Providers.Rackspace;
8+
using Stream = System.IO.Stream;
79

810
public class ObjectStorageProviderExamples
911
{
@@ -43,5 +45,53 @@ private static IEnumerable<ContainerObject> ListAllObjects(
4345
} while (lastContainerObject != null);
4446
}
4547
#endregion ListObjectsInContainer
48+
49+
#region CreateObjectFromFileWithMetadata
50+
public void CreateObjectWithMetadata(
51+
IObjectStorageProvider provider,
52+
string containerName,
53+
string objectName,
54+
string filePath)
55+
{
56+
// Method 1: Set metadata when the object is created
57+
var headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
58+
{
59+
{ CloudFilesProvider.ObjectMetaDataPrefix + "Key", "Value" }
60+
};
61+
provider.CreateObjectFromFile(containerName, filePath, objectName, headers: headers);
62+
63+
// Method 2: Set metadata in a separate call after the object is created
64+
provider.CreateObjectFromFile(containerName, filePath, objectName);
65+
var metadata = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
66+
{
67+
{ "Key", "Value" }
68+
};
69+
provider.UpdateObjectMetadata(containerName, objectName, metadata);
70+
}
71+
#endregion CreateObjectWithMetadata
72+
73+
#region CreateObjectWithMetadata
74+
public void CreateObjectWithMetadata(
75+
IObjectStorageProvider provider,
76+
string containerName,
77+
string objectName,
78+
Stream data)
79+
{
80+
// Method 1: Set metadata when the object is created
81+
var headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
82+
{
83+
{ CloudFilesProvider.ObjectMetaDataPrefix + "Key", "Value" }
84+
};
85+
provider.CreateObject(containerName, data, objectName, headers: headers);
86+
87+
// Method 2: Set metadata in a separate call after the object is created
88+
provider.CreateObject(containerName, data, objectName);
89+
var metadata = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
90+
{
91+
{ "Key", "Value" }
92+
};
93+
provider.UpdateObjectMetadata(containerName, objectName, metadata);
94+
}
95+
#endregion CreateObjectWithMetadata
4696
}
4797
}

‎src/corelib/Core/Providers/IObjectStorageProvider.cs‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1068,10 +1068,18 @@ public interface IObjectStorageProvider
10681068
/// Creates an object using data from a file. If the destination file already exists, the contents are overwritten.
10691069
/// </summary>
10701070
/// <remarks>
1071+
/// <para>
10711072
/// The content type for the object may be specified by providing the <paramref name="contentType"/> argument,
10721073
/// or by setting <see cref="CloudFilesProvider.DetectContentType"/> to <c>True</c> in the
10731074
/// <paramref name="headers"/> argument. If neither of these is used, the resulting content type of the object
10741075
/// is unspecified.
1076+
/// </para>
1077+
/// <para>
1078+
/// Object metadata can be set at the time the object is created by including the custom metadata items in the
1079+
/// <paramref name="headers"/> argument. Note that unlike the <see cref="UpdateObjectMetadata"/> method, the
1080+
/// keys of all custom metadata items included as headers must be prefixed with
1081+
/// <see cref="CloudFilesProvider.ObjectMetaDataPrefix"/>.
1082+
/// </para>
10751083
/// </remarks>
10761084
/// <param name="container">The container name.</param>
10771085
/// <param name="filePath">The source file path. Example <localUri>c:\folder1\folder2\image_name.jpeg</localUri></param>
@@ -1112,6 +1120,12 @@ public interface IObjectStorageProvider
11121120
/// <para>If <paramref name="region"/> is <see langword="null"/> and no default region is available for the provider.</para>
11131121
/// </exception>
11141122
/// <exception cref="ResponseException">If the REST API request failed.</exception>
1123+
/// <example>
1124+
/// The following code shows two ways to create an object with custom metadata. The first uses the <paramref name="headers"/>
1125+
/// argument to this method, and the second shows an alternative method of calling <see cref="UpdateObjectMetadata"/> after
1126+
/// the object is created.
1127+
/// <code source="..\Samples\CSharpCodeSamples\ObjectStorageProviderExamples.cs" region="CreateObjectFromFileWithMetadata" language="cs"/>
1128+
/// </example>
11151129
/// <seealso cref="CloudFilesProvider.DetectContentType"/>
11161130
/// <seealso href="http://docs.openstack.org/api/openstack-object-storage/1.0/content/PUT_createOrReplaceObject_v1__account___container___object__storage_object_services.html">Create or replace object (OpenStack Object Storage API v1 Reference)</seealso>
11171131
void CreateObjectFromFile(string container, string filePath, string objectName = null, string contentType = null, int chunkSize = 65536, Dictionary<string, string> headers = null, string region = null, Action<long> progressUpdated = null, bool useInternalUrl = false, CloudIdentity identity = null);
@@ -1120,10 +1134,18 @@ public interface IObjectStorageProvider
11201134
/// Creates an object using data from a <see cref="Stream"/>. If the destination file already exists, the contents are overwritten.
11211135
/// </summary>
11221136
/// <remarks>
1137+
/// <para>
11231138
/// The content type for the object may be specified by providing the <paramref name="contentType"/> argument,
11241139
/// or by setting <see cref="CloudFilesProvider.DetectContentType"/> to <c>True</c> in the
11251140
/// <paramref name="headers"/> argument. If neither of these is used, the resulting content type of the object
11261141
/// is unspecified.
1142+
/// </para>
1143+
/// <para>
1144+
/// Object metadata can be set at the time the object is created by including the custom metadata items in the
1145+
/// <paramref name="headers"/> argument. Note that unlike the <see cref="UpdateObjectMetadata"/> method, the
1146+
/// keys of all custom metadata items included as headers must be prefixed with
1147+
/// <see cref="CloudFilesProvider.ObjectMetaDataPrefix"/>.
1148+
/// </para>
11271149
/// </remarks>
11281150
/// <param name="container">The container name.</param>
11291151
/// <param name="stream">A <see cref="Stream"/> providing the data for the file.</param>
@@ -1165,6 +1187,12 @@ public interface IObjectStorageProvider
11651187
/// <para>If <paramref name="region"/> is <see langword="null"/> and no default region is available for the provider.</para>
11661188
/// </exception>
11671189
/// <exception cref="ResponseException">If the REST API request failed.</exception>
1190+
/// <example>
1191+
/// The following code shows two ways to create an object with custom metadata. The first uses the <paramref name="headers"/>
1192+
/// argument to this method, and the second shows an alternative method of calling <see cref="UpdateObjectMetadata"/> after
1193+
/// the object is created.
1194+
/// <code source="..\Samples\CSharpCodeSamples\ObjectStorageProviderExamples.cs" region="CreateObjectWithMetadata" language="cs"/>
1195+
/// </example>
11681196
/// <seealso cref="CloudFilesProvider.DetectContentType"/>
11691197
/// <seealso href="http://docs.openstack.org/api/openstack-object-storage/1.0/content/PUT_createOrReplaceObject_v1__account___container___object__storage_object_services.html">Create or replace object (OpenStack Object Storage API v1 Reference)</seealso>
11701198
void CreateObject(string container, Stream stream, string objectName, string contentType = null, int chunkSize = 65536, Dictionary<string, string> headers = null, string region = null, Action<long> progressUpdated = null, bool useInternalUrl = false, CloudIdentity identity = null);

‎src/testing/integration/Providers/Rackspace/UserObjectStorageTests.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1583,9 +1583,9 @@ public void TestCreateObjectWithMetadata()
15831583
{
15841584
Dictionary<string, string> headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
15851585
{
1586-
{ "X-Object-Meta-Projectcode", "ProjectCode" },
1587-
{ "X-Object-Meta-Filedesc", "FileDescription" },
1588-
{ "X-Object-Meta-Usercode", "User Code" },
1586+
{ CloudFilesProvider.ObjectMetaDataPrefix + "Projectcode", "ProjectCode" },
1587+
{ CloudFilesProvider.ObjectMetaDataPrefix + "Filedesc", "FileDescription" },
1588+
{ CloudFilesProvider.ObjectMetaDataPrefix + "Usercode", "User Code" },
15891589
};
15901590
provider.CreateObject(containerName, uploadStream, objectName, headers: headers);
15911591
}

0 commit comments

Comments
 (0)