WIP: Design the timeline service interface.

7 files changed, 320 insertions, 7 deletions

diff --git a/Timeline/Entities/TimelineMemberEntity.cs b/Timeline/Entities/TimelineMemberEntity.cs
index 4631dc89..c8961013 100644
--- a/Timeline/Entities/TimelineMemberEntity.cs
+++ b/Timeline/Entities/TimelineMemberEntity.cs
@@ -1,9 +1,5 @@
-using System;

-using System.Collections.Generic;

-using System.ComponentModel.DataAnnotations;

+using System.ComponentModel.DataAnnotations;

 using System.ComponentModel.DataAnnotations.Schema;

-using System.Linq;

-using System.Threading.Tasks;

 

 namespace Timeline.Entities

 {

diff --git a/Timeline/Models/Timeline.cs b/Timeline/Models/Timeline.cs
new file mode 100644
index 00000000..26012878
--- /dev/null
+++ b/Timeline/Models/Timeline.cs
@@ -0,0 +1,42 @@
+using System;

+using System.Collections.Generic;

+using System.Linq;

+using System.Threading.Tasks;

+using Timeline.Entities;

+

+namespace Timeline.Models

+{

+    public class TimelinePostInfo

+    {

+        public long Id { get; set; }

+

+        public string? Content { get; set; }

+

+        public DateTime Time { get; set; }

+

+        /// <summary>

+        /// The username of the author.

+        /// </summary>

+        public string Author { get; set; } = default!;

+    }

+

+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Usage", "CA2227:Collection properties should be read only", Justification = "This is a DTO class.")]

+    public class BaseTimelineInfo

+    {

+        public string? Description { get; set; }

+

+        /// <summary>

+        /// The username of the owner.

+        /// </summary>

+        public string Owner { get; set; } = default!;

+

+        public TimelineVisibility Visibility { get; set; }

+

+        public List<string> Members { get; set; } = default!;

+    }

+

+    public class TimelineInfo : BaseTimelineInfo

+    {

+        public string Name { get; set; } = default!;

+    }

+}

diff --git a/Timeline/Resources/Services/Exception.Designer.cs b/Timeline/Resources/Services/Exception.Designer.cs
index ddf60f45..a5785cb6 100644
--- a/Timeline/Resources/Services/Exception.Designer.cs
+++ b/Timeline/Resources/Services/Exception.Designer.cs
@@ -268,6 +268,42 @@ namespace Timeline.Resources.Services {
         }

         

         /// <summary>

+        ///   Looks up a localized string similar to An exception happened when add or remove member on timeline..

+        /// </summary>

+        internal static string TimelineMemberOperationException {

+            get {

+                return ResourceManager.GetString("TimelineMemberOperationException", resourceCulture);

+            }

+        }

+        

+        /// <summary>

+        ///   Looks up a localized string similar to An exception happened when operating on the {} member on timeline..

+        /// </summary>

+        internal static string TimelineMemberOperationExceptionIndex {

+            get {

+                return ResourceManager.GetString("TimelineMemberOperationExceptionIndex", resourceCulture);

+            }

+        }

+        

+        /// <summary>

+        ///   Looks up a localized string similar to Timeline name is of bad format. If this is a personal timeline, it means the username is of bad format and inner exception should be a UsernameBadFormatException..

+        /// </summary>

+        internal static string TimelineNameBadFormatException {

+            get {

+                return ResourceManager.GetString("TimelineNameBadFormatException", resourceCulture);

+            }

+        }

+        

+        /// <summary>

+        ///   Looks up a localized string similar to Timeline does not exist. If this is a personal timeline, it means the user does not exist and inner exception should be a UserNotExistException..

+        /// </summary>

+        internal static string TimelineNotExistException {

+            get {

+                return ResourceManager.GetString("TimelineNotExistException", resourceCulture);

+            }

+        }

+        

+        /// <summary>

         ///   Looks up a localized string similar to The username is of bad format..

         /// </summary>

         internal static string UsernameBadFormatException {

diff --git a/Timeline/Resources/Services/Exception.resx b/Timeline/Resources/Services/Exception.resx
index 12bf9afb..e6622094 100644
--- a/Timeline/Resources/Services/Exception.resx
+++ b/Timeline/Resources/Services/Exception.resx
@@ -186,6 +186,18 @@
   <data name="JwtVerifyExceptionVersionClaimBadFormat" xml:space="preserve">

     <value>version claim is not a number.</value>

   </data>

+  <data name="TimelineMemberOperationException" xml:space="preserve">

+    <value>An exception happened when add or remove member on timeline.</value>

+  </data>

+  <data name="TimelineMemberOperationExceptionIndex" xml:space="preserve">

+    <value>An exception happened when operating on the {} member on timeline.</value>

+  </data>

+  <data name="TimelineNameBadFormatException" xml:space="preserve">

+    <value>Timeline name is of bad format. If this is a personal timeline, it means the username is of bad format and inner exception should be a UsernameBadFormatException.</value>

+  </data>

+  <data name="TimelineNotExistException" xml:space="preserve">

+    <value>Timeline does not exist. If this is a personal timeline, it means the user does not exist and inner exception should be a UserNotExistException.</value>

+  </data>

   <data name="UsernameBadFormatException" xml:space="preserve">

     <value>The username is of bad format.</value>

   </data>

diff --git a/Timeline/Services/TimelineNameBadFormatException.cs b/Timeline/Services/TimelineNameBadFormatException.cs
new file mode 100644
index 00000000..5120a175
--- /dev/null
+++ b/Timeline/Services/TimelineNameBadFormatException.cs
@@ -0,0 +1,21 @@
+using System;

+

+namespace Timeline.Services

+{

+    [Serializable]

+    public class TimelineNameBadFormatException : Exception

+    {

+        public TimelineNameBadFormatException()

+            : base(Resources.Services.Exception.TimelineNameBadFormatException) { }

+        public TimelineNameBadFormatException(string name)

+            : base(Resources.Services.Exception.TimelineNameBadFormatException) { Name = name; }

+        public TimelineNameBadFormatException(string name, Exception inner)

+            : base(Resources.Services.Exception.TimelineNameBadFormatException, inner) { Name = name; }

+

+        protected TimelineNameBadFormatException(

+          System.Runtime.Serialization.SerializationInfo info,

+          System.Runtime.Serialization.StreamingContext context) : base(info, context) { }

+

+        public string? Name { get; set; }

+    }

+}

diff --git a/Timeline/Services/TimelineNotExistException.cs b/Timeline/Services/TimelineNotExistException.cs
new file mode 100644
index 00000000..6dfd0bab
--- /dev/null
+++ b/Timeline/Services/TimelineNotExistException.cs
@@ -0,0 +1,19 @@
+using System;

+

+namespace Timeline.Services

+{

+    [Serializable]

+    public class TimelineNotExistException : Exception

+    {

+        public TimelineNotExistException() : base(Resources.Services.Exception.TimelineNotExistException) { }

+        public TimelineNotExistException(string name)

+            : base(Resources.Services.Exception.TimelineNotExistException) { Name = name; }

+        public TimelineNotExistException(string name, Exception inner)

+            : base(Resources.Services.Exception.TimelineNotExistException, inner) { Name = name; }

+        protected TimelineNotExistException(

+          System.Runtime.Serialization.SerializationInfo info,

+          System.Runtime.Serialization.StreamingContext context) : base(info, context) { }

+

+        public string? Name { get; set; }

+    }

+}

diff --git a/Timeline/Services/TimelineService.cs b/Timeline/Services/TimelineService.cs
index e6a1e845..cf130a70 100644
--- a/Timeline/Services/TimelineService.cs
+++ b/Timeline/Services/TimelineService.cs
@@ -1,12 +1,199 @@
 using System;

 using System.Collections.Generic;

+using System.Globalization;

 using System.Linq;

 using System.Threading.Tasks;

+using Timeline.Entities;

+using Timeline.Models;

 

 namespace Timeline.Services

 {

-    public interface ITimelineService

+

+    [Serializable]

+    public class TimelineMemberOperationException : Exception

+    {

+        public TimelineMemberOperationException() : base(Resources.Services.Exception.TimelineMemberOperationException) { }

+        public TimelineMemberOperationException(string message) : base(message) { }

+        public TimelineMemberOperationException(string message, Exception inner) : base(message, inner) { }

+        protected TimelineMemberOperationException(

+          System.Runtime.Serialization.SerializationInfo info,

+          System.Runtime.Serialization.StreamingContext context) : base(info, context) { }

+

+        public TimelineMemberOperationException(int index, Exception inner) : base(MakeIndexMessage(index), inner) { Index = index; }

+

+        private static string MakeIndexMessage(int index) => string.Format(CultureInfo.CurrentCulture,

+            Resources.Services.Exception.TimelineMemberOperationExceptionIndex, index);

+

+        public int? Index { get; set; }

+    }

+

+    /// <summary>

+    /// This define the common interface of both personal timeline

+    /// and normal timeline.

+    /// </summary>

+    /// <remarks>

+    /// The "name" parameter in method means name of timeline in

+    /// <see cref="ITimelineService"/> while username of the owner

+    /// of the personal timeline in <see cref="IPersonalTimelineService"/>.

+    /// </remarks>

+    public interface IBaseTimelineService

+    {

+        /// <summary>

+        /// Get all the posts in the timeline.

+        /// </summary>

+        /// <param name="name">Username or the timeline name. See remarks of <see cref="IBaseTimelineService"/>.</param>

+        /// <returns>A list of all posts.</returns>

+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> is null.</exception>

+        /// <exception cref="TimelineNameBadFormatException">

+        /// Thrown when timeline name is of bad format.

+        /// For normal timeline, it means name is an empty string.

+        /// For personal timeline, it means the username is of bad format,

+        /// the inner exception should be a <see cref="UsernameBadFormatException"/>.

+        /// </exception>

+        /// <exception cref="TimelineNotExistException">

+        /// Thrown when timeline does not exist.

+        /// For normal timeline, it means the name does not exist.

+        /// For personal timeline, it means the user of that username does not exist

+        /// and the inner exception should be a <see cref="UserNotExistException"/>.

+        /// </exception>

+        Task<List<TimelinePostInfo>> GetPosts(string name);

+

+        /// <summary>

+        /// Create a new post in timeline.

+        /// </summary>

+        /// <param name="name">Username or the timeline name. See remarks of <ssee cref="IBaseTimelineService"/>.</param>

+        /// <param name="author">The author's username.</param>

+        /// <param name="content">The content.</param>

+        /// <param name="time">The time of the post. If null, then use current time.</param>

+        /// <returns></returns>

+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> or <paramref name="author"/> or <paramref name="content"/> is null.</exception>

+        /// <exception cref="TimelineNameBadFormatException">

+        /// Thrown when timeline name is of bad format.

+        /// For normal timeline, it means name is an empty string.

+        /// For personal timeline, it means the username is of bad format,

+        /// the inner exception should be a <see cref="UsernameBadFormatException"/>.

+        /// </exception>

+        /// <exception cref="TimelineNotExistException">

+        /// Thrown when timeline does not exist.

+        /// For normal timeline, it means the name does not exist.

+        /// For personal timeline, it means the user of that username does not exist

+        /// and the inner exception should be a <see cref="UserNotExistException"/>.

+        /// </exception>

+        /// <exception cref="UsernameBadFormatException">Thrown if <paramref name="author"/> is of bad format.</exception>

+        /// <exception cref="UserNotExistException">Thrown if <paramref name="author"/> does not exist.</exception>

+        Task<long> Post(string name, string author, string content, DateTime? time);

+

+        /// <summary>

+        /// Set the visibility permission of a timeline. 

+        /// </summary>

+        /// <param name="name">Username or the timeline name. See remarks of <see cref="IBaseTimelineService"/>.</param>

+        /// <param name="visibility">The new visibility.</param>

+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> is null.</exception>

+        /// <exception cref="TimelineNameBadFormatException">

+        /// Thrown when timeline name is of bad format.

+        /// For normal timeline, it means name is an empty string.

+        /// For personal timeline, it means the username is of bad format,

+        /// the inner exception should be a <see cref="UsernameBadFormatException"/>.

+        /// </exception>

+        /// <exception cref="TimelineNotExistException">

+        /// Thrown when timeline does not exist.

+        /// For normal timeline, it means the name does not exist.

+        /// For personal timeline, it means the user of that username does not exist

+        /// and the inner exception should be a <see cref="UserNotExistException"/>.

+        /// </exception>

+        Task SetVisibility(string name, TimelineVisibility visibility);

+

+        /// <summary>

+        /// Set the description of a timeline.

+        /// </summary>

+        /// <param name="name">Username or the timeline name. See remarks of <see cref="IBaseTimelineService"/>.</param>

+        /// <param name="description">The new description.</param>

+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> or <paramref name="description"/> is null.</exception>

+        /// <exception cref="TimelineNameBadFormatException">

+        /// Thrown when timeline name is of bad format.

+        /// For normal timeline, it means name is an empty string.

+        /// For personal timeline, it means the username is of bad format,

+        /// the inner exception should be a <see cref="UsernameBadFormatException"/>.

+        /// </exception>

+        /// <exception cref="TimelineNotExistException">

+        /// Thrown when timeline does not exist.

+        /// For normal timeline, it means the name does not exist.

+        /// For personal timeline, it means the user of that username does not exist

+        /// and the inner exception should be a <see cref="UserNotExistException"/>.

+        /// </exception>

+        Task SetDescription(string name, string description);

+

+        /// <summary>

+        /// Add members to a timeline.

+        /// </summary>

+        /// <param name="name">Username or the timeline name. See remarks of <see cref="IBaseTimelineService"/>.</param>

+        /// <param name="usernames">A list of new members' usernames</param>

+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> or <paramref name="usernames"/> is null.</exception>

+        /// <exception cref="TimelineNameBadFormatException">

+        /// Thrown when timeline name is of bad format.

+        /// For normal timeline, it means name is an empty string.

+        /// For personal timeline, it means the username is of bad format,

+        /// the inner exception should be a <see cref="UsernameBadFormatException"/>.

+        /// </exception>

+        /// <exception cref="TimelineNotExistException">

+        /// Thrown when timeline does not exist.

+        /// For normal timeline, it means the name does not exist.

+        /// For personal timeline, it means the user of that username does not exist

+        /// and the inner exception should be a <see cref="UserNotExistException"/>.

+        /// </exception>

+        /// <exception cref="TimelineMemberOperationException">

+        /// TODO! complete this documents.

+        /// </exception>

+        Task AddMember(string name, IList<string> usernames);

+

+        /// <summary>

+        /// Remove members to a timeline.

+        /// </summary>

+        /// <param name="name">Username or the timeline name. See remarks of <see cref="IBaseTimelineService"/>.</param>

+        /// <param name="usernames">A list of members' usernames</param>

+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> is null.</exception>

+        /// <exception cref="TimelineNameBadFormatException">

+        /// Thrown when timeline name is of bad format.

+        /// For normal timeline, it means name is an empty string.

+        /// For personal timeline, it means the username is of bad format,

+        /// the inner exception should be a <see cref="UsernameBadFormatException"/>.

+        /// </exception>

+        /// <exception cref="TimelineNotExistException">

+        /// Thrown when timeline does not exist.

+        /// For normal timeline, it means the name does not exist.

+        /// For personal timeline, it means the user of that username does not exist

+        /// and the inner exception should be a <see cref="UserNotExistException"/>.

+        /// </exception>

+        Task RemoveMember(string name, IList<string> usernames);

+    }

+

+    /// <summary>

+    /// Service for normal timeline.

+    /// </summary>

+    public interface ITimelineService : IBaseTimelineService

+    {

+        /// <summary>

+        /// Get the timeline info.

+        /// </summary>

+        /// <param name="name">The name of the timeline.</param>

+        /// <returns>The timeline info.</returns>

+        Task<TimelineInfo> GetTimeline(string name);

+

+        /// <summary>

+        /// Create a timeline.

+        /// </summary>

+        /// <param name="name">The name of the timeline.</param>

+        /// <param name="owner">The owner of the timeline.</param>

+        Task CreateTimeline(string name, string owner);

+    }

+

+    public interface IPersonalTimelineService : IBaseTimelineService

     {

-        // TODO: Design this.

+        /// <summary>

+        /// Get the timeline info.

+        /// </summary>

+        /// <param name="username">The username of the owner of the personal timeline.</param>

+        /// <returns>The timeline info.</returns>

+        Task<BaseTimelineInfo> GetTimeline(string username);

     }

 }