Added a mustUseAdvisory parameter to the Create() methods for Consumers.

Author: rafidzal

Code/Sif3Framework/Sif.Framework/Consumers/Consumer.cs

@@ -174,9 +174,9 @@ public string GetChangesSinceMarker(string zoneId = null, string contextId = nul
         }
 
         /// <summary>
-        /// <see cref="IConsumer{TSingle,TMultiple,TPrimaryKey}.Create(TSingle, string, string)">Create</see>
+        /// <see cref="IConsumer{TSingle,TMultiple,TPrimaryKey}.Create(TSingle, bool?, string, string)">Create</see>
         /// </summary>
-        public virtual TSingle Create(TSingle obj, string zoneId = null, string contextId = null)
+        public virtual TSingle Create(TSingle obj, bool? mustUseAdvisory = null, string zoneId = null, string contextId = null)
         {
 
             if (!RegistrationService.Registered)
@@ -186,17 +186,17 @@ public virtual TSingle Create(TSingle obj, string zoneId = null, string contextI
 
             string url = EnvironmentUtils.ParseServiceUrl(EnvironmentTemplate) + "/" + TypeName + "s" + "/" + TypeName + HttpUtils.MatrixParameters(zoneId, contextId);
             string body = SerialiseSingle(obj);
-            string xml = HttpUtils.PostRequest(url, RegistrationService.AuthorisationToken, body);
+            string xml = HttpUtils.PostRequest(url, RegistrationService.AuthorisationToken, body, mustUseAdvisory: mustUseAdvisory);
             if (log.IsDebugEnabled) log.Debug("XML from POST request ...");
             if (log.IsDebugEnabled) log.Debug(xml);
 
             return DeserialiseSingle(xml);
         }
 
         /// <summary>
-        /// <see cref="IConsumer{TSingle,TMultiple,TPrimaryKey}.Create(TMultiple, string, string)">Create</see>
+        /// <see cref="IConsumer{TSingle,TMultiple,TPrimaryKey}.Create(TMultiple, bool?, string, string)">Create</see>
         /// </summary>
-        public virtual MultipleCreateResponse Create(TMultiple obj, string zoneId = null, string contextId = null)
+        public virtual MultipleCreateResponse Create(TMultiple obj, bool? mustUseAdvisory = null, string zoneId = null, string contextId = null)
         {
 
             if (!RegistrationService.Registered)
@@ -206,7 +206,7 @@ public virtual MultipleCreateResponse Create(TMultiple obj, string zoneId = null
 
             string url = EnvironmentUtils.ParseServiceUrl(EnvironmentTemplate) + "/" + TypeName + "s" + HttpUtils.MatrixParameters(zoneId, contextId);
             string body = SerialiseMultiple(obj);
-            string xml = HttpUtils.PostRequest(url, RegistrationService.AuthorisationToken, body);
+            string xml = HttpUtils.PostRequest(url, RegistrationService.AuthorisationToken, body, mustUseAdvisory: mustUseAdvisory);
             if (log.IsDebugEnabled) log.Debug("XML from POST request ...");
             if (log.IsDebugEnabled) log.Debug(xml);
             createResponseType createResponseType = SerialiserFactory.GetXmlSerialiser<createResponseType>().Deserialise(xml);

Code/Sif3Framework/Sif.Framework/Consumers/IConsumer.cs

@@ -58,20 +58,22 @@ public interface IConsumer<TSingle, TMultiple, TPrimaryKey> : IPayloadSerialisab
         /// <para>POST /StudentPersonals/StudentPersonal</para>
         /// </summary>
         /// <param name="obj">Object to create.</param>
+        /// <param name="mustUseAdvisory">Flag to indicate whether the object's identifier should be retained.</param>
         /// <param name="zoneId">Zone associated with the request.</param>
         /// <param name="contextId">Zone context.</param>
         /// <returns>Created object.</returns>
-        TSingle Create(TSingle obj, string zoneId = null, string contextId = null);
+        TSingle Create(TSingle obj, bool? mustUseAdvisory = null, string zoneId = null, string contextId = null);
 
         /// <summary>
         /// Create multiple objects.
         /// <para>POST /StudentPersonals</para>
         /// </summary>
         /// <param name="obj">Object (multiple object entity) to create.</param>
+        /// <param name="mustUseAdvisory">Flag to indicate whether the object's identifier should be retained.</param>
         /// <param name="zoneId">Zone associated with the request.</param>
         /// <param name="contextId">Zone context.</param>
         /// <returns>Response containing status of each object created.</returns>
-        MultipleCreateResponse Create(TMultiple obj, string zoneId = null, string contextId = null);
+        MultipleCreateResponse Create(TMultiple obj, bool? mustUseAdvisory = null, string zoneId = null, string contextId = null);
 
         /// <summary>
         /// Retrieve a single object.

Code/Sif3Framework/Sif.Framework/Utils/HttpUtils.cs

@@ -65,6 +65,7 @@ internal enum RequestHeader
         /// <param name="methodOverride">Overrides the method of the request, e.g. to implement a GET with a payload over a POST request.</param>
         /// <param name="contentTypeOverride">Overrides the ContentType header.</param>
         /// <param name="acceptOverride">Overrides the Accept header.</param>
+        /// <param name="mustUseAdvisory">Flag to indicate whether the object's identifier should be retained.</param>
         /// <returns>HTTP web request.</returns>
         private static HttpWebRequest CreateHttpWebRequest(RequestMethod requestMethod,
             string url,
@@ -74,7 +75,8 @@ private static HttpWebRequest CreateHttpWebRequest(RequestMethod requestMethod,
             int? navigationPageSize = null,
             string methodOverride = null,
             string contentTypeOverride = null,
-            string acceptOverride = null)
+            string acceptOverride = null,
+            bool? mustUseAdvisory = null)
         {
             HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
             request.ContentType = "application/xml";
@@ -125,6 +127,11 @@ private static HttpWebRequest CreateHttpWebRequest(RequestMethod requestMethod,
                 request.ContentType = contentTypeOverride.Trim();
             }
 
+            if (mustUseAdvisory.HasValue)
+            {
+                request.Headers.Add(RequestHeader.mustUseAdvisory.ToDescription(), mustUseAdvisory.Value.ToString());
+            }
+
             return request;
         }
 
@@ -224,6 +231,7 @@ private static string RequestWithoutPayload(RequestMethod requestMethod,
         /// <param name="methodOverride">Overrides the method of the request, e.g. to implement a GET with a payload over a POST request.</param>
         /// <param name="contentTypeOverride">Overrides the ContentType header.</param>
         /// <param name="acceptOverride">Overrides the Accept header.</param>
+        /// <param name="mustUseAdvisory">Flag to indicate whether the object's identifier should be retained.</param>
         /// <returns>Response.</returns>
         private static string RequestWithPayload(RequestMethod requestMethod,
             string url,
@@ -232,9 +240,10 @@ private static string RequestWithPayload(RequestMethod requestMethod,
             ServiceType? serviceType = null,
             string methodOverride = null,
             string contentTypeOverride = null,
-            string acceptOverride = null)
+            string acceptOverride = null,
+            bool? mustUseAdvisory = null)
         {
-            HttpWebRequest request = CreateHttpWebRequest(requestMethod, url, authorisationToken, serviceType, null, null, methodOverride, contentTypeOverride, acceptOverride);
+            HttpWebRequest request = CreateHttpWebRequest(requestMethod, url, authorisationToken, serviceType, null, null, methodOverride, contentTypeOverride, acceptOverride, mustUseAdvisory);
 
             using (Stream requestStream = request.GetRequestStream())
             {
@@ -377,16 +386,18 @@ public static WebHeaderCollection HeadRequest(string url, AuthorisationToken aut
         /// <param name="methodOverride">The method that can be used to override the POST, e.g. to issue a GET with a payload.</param>
         /// <param name="contentTypeOverride">Overrides the ContentType header.</param>
         /// <param name="acceptOverride">Overrides the Accept header.</param>
+        /// <param name="mustUseAdvisory">Flag to indicate whether the object's identifier should be retained.</param>
         /// <returns>Response.</returns>
         public static string PostRequest(string url,
             AuthorisationToken authorisationToken,
             string body,
             ServiceType serviceType = ServiceType.OBJECT,
             string methodOverride = null,
             string contentTypeOverride = null,
-            string acceptOverride = null)
+            string acceptOverride = null,
+            bool? mustUseAdvisory = null)
         {
-            return RequestWithPayload(RequestMethod.POST, url, authorisationToken, body, serviceType, methodOverride, contentTypeOverride, acceptOverride);
+            return RequestWithPayload(RequestMethod.POST, url, authorisationToken, body, serviceType, methodOverride, contentTypeOverride, acceptOverride, mustUseAdvisory);
         }
 
         /// <summary>

Code/Sif3FrameworkDemo/Sif.Framework.Demo.Au.Consumer/ConsumerApp.cs

@@ -93,9 +93,10 @@ void RunStudentPersonalConsumer()
                 SIF_ExtendedElementsTypeSIF_ExtendedElement[] extendedElements = new SIF_ExtendedElementsTypeSIF_ExtendedElement[] { extendedElement };
                 NameOfRecordType newStudentName = new NameOfRecordType { FamilyName = "Wayne", GivenName = "Bruce", Type = NameOfRecordTypeType.LGL };
                 PersonInfoType newStudentInfo = new PersonInfoType { Name = newStudentName };
-                StudentPersonal newStudent = new StudentPersonal { LocalId = "555", PersonInfo = newStudentInfo, SIF_ExtendedElements = extendedElements };
-                StudentPersonal retrievedNewStudent = studentPersonalConsumer.Create(newStudent);
-                if (log.IsInfoEnabled) log.Info("Created new student " + newStudent.PersonInfo.Name.GivenName + " " + newStudent.PersonInfo.Name.FamilyName);
+                string studentID = Guid.NewGuid().ToString();
+                StudentPersonal newStudent = new StudentPersonal { RefId = studentID, LocalId = "555", PersonInfo = newStudentInfo, SIF_ExtendedElements = extendedElements };
+                StudentPersonal retrievedNewStudent = studentPersonalConsumer.Create(newStudent, true);
+                if (log.IsInfoEnabled) log.Info($"Created new student {newStudent.PersonInfo.Name.GivenName} {newStudent.PersonInfo.Name.FamilyName} with ID of {studentID}.");
 
                 // Create multiple new students.
                 if (log.IsInfoEnabled) log.Info("*** Create multiple new students.");

Code/Sif3FrameworkDemo/Sif.Framework.Demo.Au.Provider/Services/StudentPersonalService.cs

@@ -115,9 +115,14 @@ static StudentPersonalService()
 
         public StudentPersonal Create(StudentPersonal obj, bool? mustUseAdvisory = null, string zoneId = null, string contextId = null)
         {
-            string refId = Guid.NewGuid().ToString();
-            obj.RefId = refId;
-            studentsCache.Add(refId, obj);
+
+            if (!mustUseAdvisory.HasValue || !mustUseAdvisory.Value)
+            {
+                string refId = Guid.NewGuid().ToString();
+                obj.RefId = refId;
+            }
+
+            studentsCache.Add(obj.RefId, obj);
 
             return obj;
         }