Implement DeprecationPolicyBuilder

Author: Matthias Gessinger

src/Abstractions/src/Asp.Versioning.Abstractions/IDeprecationPolicyBuilder.cs

@@ -0,0 +1,24 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+/// <summary>
+/// Defines the behavior of a deprecation policy builder.
+/// </summary>
+public interface IDeprecationPolicyBuilder : IPolicyBuilder<DeprecationPolicy>
+{
+    /// <summary>
+    /// Creates and returns a new link builder.
+    /// </summary>
+    /// <param name="linkTarget">The link target URL.</param>
+    /// <returns>A new <see cref="ILinkBuilder">link builder</see>.</returns>
+    ILinkBuilder Link( Uri linkTarget );
+
+    /// <summary>
+    /// Indicates when a deprecation policy is applied.
+    /// </summary>
+    /// <param name="deprecationDate">The <see cref="DateTimeOffset">date and time</see> when a
+    /// deprecation policy is applied.</param>
+    /// <returns>The current <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</returns>
+    IDeprecationPolicyBuilder Effective( DateTimeOffset deprecationDate );
+}

src/Abstractions/src/Asp.Versioning.Abstractions/IDeprecationPolicyBuilderExtensions.cs

@@ -0,0 +1,38 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+/// <summary>
+/// Provides extension methods for the <see cref="IDeprecationPolicyBuilder"/> interface.
+/// </summary>
+public static class IDeprecationPolicyBuilderExtensions
+{
+    /// <summary>
+    /// Creates and returns a new link builder.
+    /// </summary>
+    /// <param name="builder">The extended <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</param>
+    /// <param name="linkTarget">The link target URL.</param>
+    /// <returns>A new <see cref="ILinkBuilder">link builder</see>.</returns>
+    public static ILinkBuilder Link( this IDeprecationPolicyBuilder builder, string linkTarget )
+    {
+        ArgumentNullException.ThrowIfNull( builder );
+        return builder.Link( new Uri( linkTarget, UriKind.RelativeOrAbsolute ) );
+    }
+
+    /// <summary>
+    /// Indicates when a deprecation policy is applied.
+    /// </summary>
+    /// <typeparam name="TBuilder">The type of <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</typeparam>
+    /// <param name="builder">The extended <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</param>
+    /// <param name="year">The year when the deprecation policy is applied.</param>
+    /// <param name="month">The month when the deprecation policy is applied.</param>
+    /// <param name="day">The day when the deprecation policy is applied.</param>
+    /// <returns>The current <see cref="IDeprecationPolicyBuilder">deprecation policy builder</see>.</returns>
+    public static TBuilder Effective<TBuilder>( this TBuilder builder, int year, int month, int day )
+        where TBuilder : notnull, IDeprecationPolicyBuilder
+    {
+        ArgumentNullException.ThrowIfNull( builder );
+        builder.Effective( new DateTimeOffset( new DateTime( year, month, day ) ) );
+        return builder;
+    }
+}

src/Common/src/Common/DeprecationPolicyBuilder.cs

@@ -0,0 +1,100 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning;
+
+/// <summary>
+/// Represents the default deprecation policy builder.
+/// </summary>
+public class DeprecationPolicyBuilder : PolicyBuilder<DeprecationPolicy>, IDeprecationPolicyBuilder
+{
+    private DateTimeOffset? date;
+    private DeprecationLinkBuilder? linkBuilder;
+    private Dictionary<Uri, DeprecationLinkBuilder>? linkBuilders;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DeprecationPolicyBuilder"/> class.
+    /// </summary>
+    /// <param name="name">The name of the API the policy is for.</param>
+    /// <param name="apiVersion">The <see cref="ApiVersion">API version</see> the policy is for.</param>
+    public DeprecationPolicyBuilder( string? name, ApiVersion? apiVersion )
+        : base( name, apiVersion ) { }
+
+    /// <inheritdoc />
+    public virtual IDeprecationPolicyBuilder Effective( DateTimeOffset deprecationDate )
+    {
+        date = deprecationDate;
+        return this;
+    }
+
+    /// <inheritdoc />
+    public virtual ILinkBuilder Link( Uri linkTarget )
+    {
+        DeprecationLinkBuilder newLinkBuilder;
+
+        if ( linkBuilder == null )
+        {
+            linkBuilder = newLinkBuilder = new( this, linkTarget );
+        }
+        else if ( linkBuilder.LinkTarget.Equals( linkTarget ) )
+        {
+            return linkBuilder;
+        }
+        else if ( linkBuilders == null )
+        {
+            linkBuilders = new()
+            {
+                [linkBuilder.LinkTarget] = linkBuilder,
+                [linkTarget] = newLinkBuilder = new( this, linkTarget ),
+            };
+        }
+        else if ( !linkBuilders.TryGetValue( linkTarget, out newLinkBuilder! ) )
+        {
+            linkBuilders.Add( linkTarget, newLinkBuilder = new( this, linkTarget ) );
+        }
+
+        return newLinkBuilder;
+    }
+
+    /// <inheritdoc />
+    public override DeprecationPolicy Build()
+    {
+        if ( Policy is not null )
+        {
+            return Policy;
+        }
+
+        DeprecationPolicy policy = date is null ? new() : new( date.Value );
+
+        if ( linkBuilders == null )
+        {
+            if ( linkBuilder != null )
+            {
+                policy.Links.Add( linkBuilder.Build() );
+            }
+        }
+        else
+        {
+            foreach ( var builder in linkBuilders.Values )
+            {
+                policy.Links.Add( builder.Build() );
+            }
+        }
+
+        return policy;
+    }
+
+    private sealed class DeprecationLinkBuilder : LinkBuilder, ILinkBuilder
+    {
+        protected override string RelationType => "deprecation";
+
+        private readonly DeprecationPolicyBuilder policyBuilder;
+
+        public DeprecationLinkBuilder( DeprecationPolicyBuilder policy, Uri linkTarget )
+            : base( linkTarget )
+        {
+            policyBuilder = policy;
+        }
+
+        public override ILinkBuilder Link( Uri linkTarget ) => policyBuilder.Link( linkTarget );
+    }
+}

src/Common/src/Common/PolicyBuilder.cs

@@ -21,7 +21,7 @@ public abstract class PolicyBuilder<TPolicy> : IPolicyBuilder<TPolicy>
     /// </summary>
     /// <param name="name">The name of the API the policy is for.</param>
     /// <param name="apiVersion">The <see cref="ApiVersion">API version</see> the policy is for.</param>
-    public PolicyBuilder( string? name, ApiVersion? apiVersion )
+    protected PolicyBuilder( string? name, ApiVersion? apiVersion )
     {
         if ( string.IsNullOrEmpty( name ) && apiVersion == null )
         {