[DEVTOOLING-1526] YearMonth type support for .Net

resources/sdk/pureclouddotnet/extensions/Client/YearMonth.cs

@@ -0,0 +1,194 @@
+using System;
+using System.Linq;
+using System.IO;
+using System.Text;
+using System.Collections;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Runtime.Serialization;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+
+namespace {{=it.packageName}}.Client
+{
+    /// <summary>
+    /// YearMonth
+    /// </summary>
+    [DataContract]
+    public partial class YearMonth :  IEquatable<YearMonth>
+    {
+        private int? year;
+        private int? month;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="YearMonth" /> class.
+        /// </summary>
+        /// <param name="Year">Year.</param>
+        /// <param name="Month">Month.</param>
+        public YearMonth(int? Year = null, int? Month = null)
+        {
+            if (Year == null || Year < 0 || Year > 9999)
+            {
+                throw new ArgumentException("YearMonth Error - Year must be between 0 and 9999");
+            }
+            if (Month == null || Month < 1 || Month > 12)
+            {
+                throw new ArgumentException("YearMonth Error - Month must be between 1 and 12");
+            }
+            this.year = Year;
+            this.month = Month;
+
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="YearMonth" /> class.
+        /// </summary>
+        /// <param name="Date">Date.</param>
+        public YearMonth(DateTime Date)
+        {
+            this.year = Date.Year;
+            this.month = Date.Month;
+
+        }
+
+        /// <summary>
+        /// Gets or Sets Year
+        /// </summary>
+        [DataMember(Name="year", EmitDefaultValue=false)]
+        public int? Year
+        {
+            get
+            {
+                return this.year;
+            }
+            set
+            {
+                if (value == null || value < 0 || value > 9999)
+                {
+                    throw new ArgumentException("YearMonth Error - Year must be between 0 and 9999");
+                }
+                this.year = value;
+            }
+        }
+
+        /// <summary>
+        /// Gets or Sets MonthValue
+        /// </summary>
+        [DataMember(Name="month", EmitDefaultValue=false)]
+        public int? Month
+        {
+            get
+            {
+                return this.month;
+            }
+            set
+            {
+                if (value == null || value < 1 || value > 12)
+                {
+                    throw new ArgumentException("YearMonth Error - Month must be between 1 and 12");
+                }
+                this.month = value;
+            }
+        }
+
+        /// <summary>
+        /// Returns the DateTime presentation of the object
+        /// </summary>
+        /// <returns>DateTime presentation of the object</returns>
+        public DateTime? ToDate()
+        {
+            if (this.Year == null || this.Month == null) return null;
+            DateTime date = new DateTime(this.Year ?? 0, this.Month ?? 0, 1);
+            return date;
+        }
+
+        /// <summary>
+        /// Returns the string presentation of the object
+        /// </summary>
+        /// <returns>String presentation of the object</returns>
+        public override string ToString()
+        {
+            // JSM Choose
+            // return String.Format("{0:0000}", this.Year) + "-" + String.Format("{0:00}", this.Month);
+            var sb = new StringBuilder();
+            sb.Append("class YearMonth {\n");
+
+            sb.Append("  Year: ").Append(Year).Append("\n");
+            sb.Append("  Month: ").Append(Month).Append("\n");
+            sb.Append("}\n");
+            return sb.ToString();
+        }
+
+        /// <summary>
+        /// Returns the JSON string presentation of the object
+        /// </summary>
+        /// <returns>JSON string presentation of the object</returns>
+        public string ToJson()
+        {
+            // JSM Choose
+            // return String.Format("{0:0000}", this.Year) + "-" + String.Format("{0:00}", this.Month);
+            return JsonConvert.SerializeObject(this, new JsonSerializerSettings
+            {
+                MetadataPropertyHandling = MetadataPropertyHandling.Ignore,
+                Formatting = Formatting.Indented
+            });
+        }
+
+        /// <summary>
+        /// Returns true if objects are equal
+        /// </summary>
+        /// <param name="obj">Object to be compared</param>
+        /// <returns>Boolean</returns>
+        public override bool Equals(object obj)
+        {
+            // credit: http://stackoverflow.com/a/10454552/677735
+            return this.Equals(obj as YearMonth);
+        }
+
+        /// <summary>
+        /// Returns true if YearMonth instances are equal
+        /// </summary>
+        /// <param name="other">Instance of YearMonth to be compared</param>
+        /// <returns>Boolean</returns>
+        public bool Equals(YearMonth other)
+        {
+            // credit: http://stackoverflow.com/a/10454552/677735
+            if (other == null)
+                return false;
+
+            return true &&
+                (
+                    this.Year == other.Year ||
+                    this.Year != null &&
+                    this.Year.Equals(other.Year)
+                ) &&
+                (
+                    this.Month == other.Month ||
+                    this.Month != null &&
+                    this.Month.Equals(other.Month)
+                );
+        }
+
+        /// <summary>
+        /// Gets the hash code
+        /// </summary>
+        /// <returns>Hash code</returns>
+        public override int GetHashCode()
+        {
+            // credit: http://stackoverflow.com/a/263416/677735
+            unchecked // Overflow is fine, just wrap
+            {
+                int hash = 41;
+                // Suitable nullity checks etc, of course :)
+                if (this.Year != null)
+                    hash = hash * 59 + this.Year.GetHashCode();
+
+                if (this.Month != null)
+                    hash = hash * 59 + this.Month.GetHashCode();
+
+                return hash;
+            }
+        }
+    }
+
+}

resources/sdk/pureclouddotnet/extensions/Client/YearMonthConverter.cs

@@ -0,0 +1,59 @@
+using System;
+using System.Globalization;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Reflection;
+using System.Runtime.Serialization;
+using Newtonsoft.Json;
+
+namespace {{=it.packageName}}.Client
+{
+    ///<Summary>
+    /// Extends JSON Converter Class for YearMonth
+    ///</Summary>
+    public class YearMonthConverter : JsonConverter
+    {
+        ///<Summary>
+        /// Determines if objectType can be converted.
+        ///</Summary>
+        public override bool CanConvert(Type objectType)
+        {
+            return (objectType == typeof(YearMonth)) || (Nullable.GetUnderlyingType(objectType) == typeof(YearMonth));
+        }
+
+        ///<Summary>
+        /// Writes YearMonth value to JSON
+        ///</Summary>
+        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        {
+            YearMonth ym = (YearMonth) value;
+            writer.WriteValue(String.Format("{0:0000}", ym.Year) + "-" + String.Format("{0:00}", ym.Month));
+        }
+
+        ///<Summary>
+        /// Reads YearMonth value from JSON
+        ///</Summary>
+        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
+        {
+            switch (reader.TokenType)
+            {
+                case JsonToken.String:
+                    var ymText = reader.Value.ToString();
+                    string[] ymSubs = ymText.Split('-');
+                    if (ymSubs != null && ymSubs.Length == 2)
+                    {
+                        int year = Int32.Parse(ymSubs[0]);
+                        int month = Int32.Parse(ymSubs[1]);
+                        YearMonth ymValue = new YearMonth(year,month);
+                        return ymValue;
+                    }
+                    break;
+                default:
+                    return null;
+            }
+
+            return null;
+        }
+    }
+}

resources/sdk/pureclouddotnet/templates/ApiClient.mustache

@@ -30,6 +30,13 @@ namespace {{packageName}}.Client
             MetadataPropertyHandling = MetadataPropertyHandling.Ignore
         };
 
+        // Future - To enable for serialization (currently unused)
+        // private JsonSerializerSettings apiSerializerSettings = new JsonSerializerSettings
+        // {
+        //     ConstructorHandling = ConstructorHandling.AllowNonPublicDefaultConstructor,
+        //     MetadataPropertyHandling = MetadataPropertyHandling.Ignore
+        // };
+
         /// <summary>
         /// Initializes a new instance of the <see cref="ApiClient" /> class
         /// with default configuration and base path ({{basePath}}).
@@ -94,6 +101,9 @@ namespace {{packageName}}.Client
         {
             serializerSettings.Converters.Add(new Iso8601DateTimeConverter());
             serializerSettings.Converters.Add(new UpgradeSdkEnumConverter());
+            serializerSettings.Converters.Add(new YearMonthConverter());
+            // Future - To enable for serialization (currently unused)
+            // apiSerializerSettings.Converters.Add(new YearMonthConverter());
         }
 
         /// <summary>
@@ -467,6 +477,11 @@ namespace {{packageName}}.Client
             {
                 return Convert.ToString(obj).ToLower();
             }
+            else if (obj is YearMonth)
+            {
+                YearMonth ym = (YearMonth) obj;
+                return String.Format("{0:0000}", ym.Year) + "-" + String.Format("{0:00}", ym.Month);
+            }
             else
                 return Convert.ToString (obj);
         }
@@ -562,6 +577,8 @@ namespace {{packageName}}.Client
             {
                 if (obj != null){
                     return obj is string str ? str : JsonConvert.SerializeObject(obj);
+                    // Future - To enable for serialization (currently unused)
+                    // return obj is string str ? str : JsonConvert.SerializeObject(obj, apiSerializerSettings);
                 } else {
                     return null;
                 }

resources/sdk/pureclouddotnet/templates/README.mustache

@@ -474,6 +474,23 @@ The .Net Platform API Client SDK implements the following strategy to manage the
 * Each enumeration, generated from the Platform API OpenAPI v2 definition, always contains the following enumeration value: `[EnumMember(Value = "OUTDATED_SDK_VERSION")] OutdatedSdkVersion`
 * If an unknown enumeration value is received (i.e. a new enumeration value, introduced in Platform API, after the SDK version you are using was built), the SDK will map it to the `[EnumMember(Value = "OUTDATED_SDK_VERSION")] OutdatedSdkVersion` enumeration value. This is to prevent errors during deserialization when an unknown enumeration value is received from Genesys Cloud.
 
+### SDK Specific Types and Classes
+
+The Platform API Client SDK for .Net defines some types and classes specific to the SDK.
+
+#### YearMonth
+
+Some API Endpoints of the Platform API (REST API) contain properties defined as string with a "year-month" format (e.g. value equal to "2026-01").  
+If part of an API Response, these properties will be deserialized to the SDK's YearMonth class.  
+YearMonth class instance will be serialized to "year-month" string format if part of an API Request (REST API).
+
+You can import the YearMonth class in your C# code with: `using {{packageName}}.Client;`  
+The YearMonth class is defined in the `{{packageName}}.Client` namespace.
+
+The YearMonth class contains two properties of integer type: **Year** (allowing value from 0 to 9999) and **Month** (allowing value from 1 to 12).  
+An instance of the class can be created using the class constructor `YearMonth(int? Year = null, int? Month = null)` or parsing a `DateTime` with `YearMonth(DateTime Date)`.  
+A YearMonth instance can also be transformed into a DateTime (with day being forced to 1) with `myYearMonth.ToDate()`.
+
 ## NotificationHandler Helper Class
 
 The .NET SDK includes a helper class `NotificationHandler` to assist in managing GenesysCloud notifications. The class will create a single notification channel, or use an existing one, and provides methods to add and remove subscriptions and raises an event with a deserialized notification object whenever one is received.

resources/sdk/purecloudjava/templates/ApiClient.mustache

@@ -527,6 +527,13 @@ public class ApiClient implements AutoCloseable {
         }
     }
 
+    /**
+     * Format the given YearMonth object into string.
+     */
+    public String formatYearMonth(YearMonth ym) {
+        return ym.toString();
+    }
+
     /**
      * Format the given parameter object into string.
      */
@@ -546,6 +553,8 @@ public class ApiClient implements AutoCloseable {
             return b.toString();
         } else if (param instanceof Boolean) {
             return String.valueOf(param).toLowerCase();
+        } else if (param instanceof YearMonth) {
+            return formatYearMonth((YearMonth) param);
         } else {
             return String.valueOf(param);
         }