Add the ResourceIdentifier<T> abstract base class

Author: sharwell

src/corelib/Core/ResourceIdentifier`1.cs

@@ -0,0 +1,155 @@
+namespace net.openstack.Core
+{
+    using System;
+    using net.openstack.Core.Domain.Converters;
+
+    /// <summary>
+    /// Represents a unique identifier within the context of a cloud services provider.
+    /// </summary>
+    /// <typeparam name="T">The resource identifier type.</typeparam>
+    /// <threadsafety static="true" instance="false"/>
+    /// <preliminary/>
+    public abstract class ResourceIdentifier<T> : IEquatable<T>
+        where T : ResourceIdentifier<T>
+    {
+        /// <summary>
+        /// This is the backing field for the <see cref="Value"/> property.
+        /// </summary>
+        private readonly string _id;
+
+        /// <summary>
+        /// Initialized a new instance of the <see cref="ResourceIdentifier{T}"/> class
+        /// with the specified identifier.
+        /// </summary>
+        /// <param name="id">The resource identifier value.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="id"/> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="id"/> is empty.</exception>
+        protected ResourceIdentifier(string id)
+        {
+            if (id == null)
+                throw new ArgumentNullException("id");
+            if (string.IsNullOrEmpty(id))
+                throw new ArgumentException("id cannot be empty");
+
+            _id = id;
+        }
+
+        /// <summary>
+        /// Determines whether two specified resource identifiers have the same value.
+        /// </summary>
+        /// <param name="left">The first resource identifier to compare, or <c>null</c>.</param>
+        /// <param name="right">The second resource identifier to compare, or <c>null</c>.</param>
+        /// <returns><c>true</c> if the value of <paramref name="left"/> is the same as the value of <paramref name="right"/>; otherwise, <c>false</c>.</returns>
+        public static bool operator ==(ResourceIdentifier<T> left, ResourceIdentifier<T> right)
+        {
+            if (object.ReferenceEquals(left, null))
+                return object.ReferenceEquals(right, null);
+            else if (object.ReferenceEquals(right, null))
+                return false;
+
+            return left.Equals(right);
+        }
+
+        /// <summary>
+        /// Determines whether two specified resource identifiers have different values.
+        /// </summary>
+        /// <param name="left">The first resource identifier to compare, or <c>null</c>.</param>
+        /// <param name="right">The second resource identifier to compare, or <c>null</c>.</param>
+        /// <returns><c>true</c> if the value of <paramref name="left"/> is different from the value of <paramref name="right"/>; otherwise, <c>false</c>.</returns>
+        public static bool operator !=(ResourceIdentifier<T> left, ResourceIdentifier<T> right)
+        {
+            return !(left == right);
+        }
+
+        /// <summary>
+        /// Gets the value of this resource identifier.
+        /// </summary>
+        public string Value
+        {
+            get
+            {
+                return _id;
+            }
+        }
+
+        /// <inheritdoc/>
+        /// <remarks>
+        /// The default implementation uses <see cref="StringComparer.Ordinal"/> to compare
+        /// the <see cref="Value"/> property of two identifiers.
+        ///
+        /// <note type="implement">
+        /// This method may be overridden to change the way unique identifiers are compared.
+        /// </note>
+        /// </remarks>
+        public virtual bool Equals(T other)
+        {
+            if (object.ReferenceEquals(other, null))
+                return false;
+
+            return StringComparer.Ordinal.Equals(_id, other._id);
+        }
+
+        /// <inheritdoc/>
+        public override bool Equals(object obj)
+        {
+            return this.Equals(obj as T);
+        }
+
+        /// <inheritdoc/>
+        /// <remarks>
+        /// The default implementation uses <see cref="StringComparer.Ordinal"/> to calculate
+        /// and return a hash code from the <see cref="Value"/> property.
+        ///
+        /// <note type="implement">
+        /// This method may be overridden to change the way unique identifiers are compared.
+        /// </note>
+        /// </remarks>
+        public override int GetHashCode()
+        {
+            return StringComparer.Ordinal.GetHashCode(_id);
+        }
+
+        /// <inheritdoc/>
+        public override string ToString()
+        {
+            return _id;
+        }
+
+        /// <summary>
+        /// Provides support for serializing and deserializing <see cref="ResourceIdentifier{T}"/>
+        /// objects to JSON string values.
+        /// </summary>
+        /// <threadsafety static="true" instance="false"/>
+        protected abstract class ConverterBase : SimpleStringJsonConverter<T>
+        {
+            /// <remarks>
+            /// This method uses <see cref="Value"/> for serialization.
+            /// </remarks>
+            /// <inheritdoc/>
+            protected override string ConvertToString(T obj)
+            {
+                return obj.Value;
+            }
+
+            /// <remarks>
+            /// If <paramref name="str"/> is <c>null</c> or an empty string, this method returns <c>null</c>.
+            /// Otherwise, this method uses <see cref="FromValue"/> for deserialization.
+            /// </remarks>
+            /// <inheritdoc/>
+            protected override T ConvertToObject(string str)
+            {
+                if (string.IsNullOrEmpty(str))
+                    return null;
+
+                return FromValue(str);
+            }
+
+            /// <summary>
+            /// Creates a resource identifier with the given value.
+            /// </summary>
+            /// <param name="id">The resource identifier value. This value is never <c>null</c> or empty.</param>
+            /// <returns>An instance of <typeparamref name="T"/> corresponding representing the specified <paramref name="id"/>.</returns>
+            protected abstract T FromValue(string id);
+        }
+    }
+}

src/corelib/corelib.v3.5.csproj

@@ -108,6 +108,7 @@
     <Compile Include="Core\ExtensibleEnum`1.cs" />
     <Compile Include="Core\NamespaceDoc.cs" />
     <Compile Include="Core\Providers\NamespaceDoc.cs" />
+    <Compile Include="Core\ResourceIdentifier`1.cs" />
     <Compile Include="Core\ResponseExtensions.cs" />
     <Compile Include="Core\RestWebHeaderCollection.cs" />
     <Compile Include="Core\Validators\NamespaceDoc.cs" />

src/corelib/corelib.v4.0.csproj

@@ -98,6 +98,7 @@
     <Compile Include="Core\ExtensibleEnum`1.cs" />
     <Compile Include="Core\NamespaceDoc.cs" />
     <Compile Include="Core\Providers\NamespaceDoc.cs" />
+    <Compile Include="Core\ResourceIdentifier`1.cs" />
     <Compile Include="Core\ResponseExtensions.cs" />
     <Compile Include="Core\RestWebHeaderCollection.cs" />
     <Compile Include="Core\Validators\NamespaceDoc.cs" />