//-----------------------------------------------------------------------
// <copyright file="SecurityTokenHandler.cs" company="Microsoft">
//     Copyright (c) Microsoft Corporation.  All rights reserved.
// </copyright>
//-----------------------------------------------------------------------

namespace System.IdentityModel.Tokens
{
    using System.Collections.ObjectModel;
    using System.IdentityModel.Configuration;
    using System.IdentityModel.Diagnostics.Application;
    using System.IdentityModel.Selectors;
    using System.Runtime.Diagnostics;
    using System.Security.Claims;
    using System.Xml;

    /// <summary>
    /// Defines the interface for a Security Token Handler.
    /// </summary>
    public abstract class SecurityTokenHandler : ICustomIdentityConfiguration
    {
        private SecurityTokenHandlerCollection collection;
        private SecurityTokenHandlerConfiguration configuration;
        private EventTraceActivity eventTraceActivity;

        /// <summary>
        /// Creates an instance of <see cref="SecurityTokenHandler"/>
        /// </summary>
        protected SecurityTokenHandler()
        {
        }

        private EventTraceActivity EventTraceActivity
        {
            get
            {
                if (this.eventTraceActivity == null)
                {
                    this.eventTraceActivity = EventTraceActivity.GetFromThreadOrCreate();
                }

                return this.eventTraceActivity;
            }
        }

        /// <summary>
        /// Gets a value indicating whether this handler supports validation of tokens 
        /// handled by this instance.
        /// </summary>v
        /// <returns>'True' if the instance is capable of SecurityToken
        /// validation.</returns>
        public virtual bool CanValidateToken
        {
            get { return false; }
        }

        /// <summary>
        /// Gets a value indicating whether the class provides serialization functionality to serialize token handled 
        /// by this instance.
        /// </summary>
        /// <returns>true if the WriteToken method can serialize this token.</returns>
        public virtual bool CanWriteToken
        {
            get { return false; }
        }

        /// <summary>
        /// Gets or sets the <see cref="SecurityTokenHandlerConfiguration" />
        /// </summary>
        public SecurityTokenHandlerConfiguration Configuration
        {
            get { return this.configuration; }
            set { this.configuration = value; }
        }

        /// <summary>
        /// Gets or sets the SecurityTokenHandlerCollection that this SecurityTokenHandler
        /// is part of. This property should never be set directly. When the SecurityTokenHandler
        /// is added to a collection this property is automatically set.
        /// </summary>
        public SecurityTokenHandlerCollection ContainingCollection
        {
            get 
            { 
                return this.collection;
            }

            internal set 
            { 
                this.collection = value;
            }
        }

        /// <summary>
        /// Gets the System.Type of the SecurityToken this instance handles.
        /// </summary>
        public abstract Type TokenType
        {
            get;
        }

        /// <summary>
        /// Indicates whether the current XML element can be read as a token 
        /// of the type handled by this instance.
        /// </summary>
        /// <param name="reader">An XML reader positioned at a start 
        /// element. The reader should not be advanced.</param>
        /// <returns>'True' if the ReadToken method can the element.</returns>
        public virtual bool CanReadToken(XmlReader reader)
        {
            return false;
        }

        /// <summary>
        /// Indicates whether the current token string can be read as a token 
        /// of the type handled by this instance.
        /// </summary>
        /// <param name="tokenString">The token string thats needs to be read.</param>
        /// <returns>'True' if the ReadToken method can parse the token string.</returns>
        public virtual bool CanReadToken(string tokenString)
        {
            return false;
        }
        
        /// <summary>
        /// Deserializes from XML a token of the type handled by this instance.
        /// </summary>
        /// <param name="reader">An XML reader positioned at the token's start 
        /// element.</param>
        /// <returns>SecurityToken instance.</returns>
        public virtual SecurityToken ReadToken(XmlReader reader)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "ReadToken")));
        }

        /// <summary>
        /// Deserializes from XML a token of the type handled by this instance.
        /// </summary>
        /// <param name="reader">An XML reader positioned at the token's start 
        /// element.</param>
        /// <param name="tokenResolver">The SecrityTokenResolver that contains out-of-band and cached tokens.</param>
        /// <returns>SecurityToken instance.</returns>
        public virtual SecurityToken ReadToken(XmlReader reader, SecurityTokenResolver tokenResolver)
        {
            // The default implementation ignores the SecurityTokenResolver and delegates the call to the 
            // ReadToken method that takes a XmlReader.
            return this.ReadToken(reader);
        }

        /// <summary>
        /// Deserializes from string a token of the type handled by this instance.
        /// </summary>
        /// <param name="tokenString">The string to be deserialized.</param>
        /// <returns>SecurityToken instance which represents the serialized token.</returns>
        public virtual SecurityToken ReadToken(string tokenString)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "ReadToken")));
        }

        /// <summary>
        /// Serializes to XML a token of the type handled by this instance.
        /// </summary>
        /// <param name="writer">The XML writer.</param>
        /// <param name="token">A token of type TokenType.</param>
        public virtual void WriteToken(XmlWriter writer, SecurityToken token)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "WriteToken")));
        }

        /// <summary>
        /// Serializes to string a token of the type handled by this instance.
        /// </summary>
        /// <param name="token">A token of type TokenType.</param>
        /// <returns>The serialized token.</returns>
        public virtual string WriteToken(SecurityToken token)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "WriteToken")));
        }

        /// <summary>
        /// Indicates if the current XML element is pointing to a KeyIdentifierClause that
        /// can be serialized by this instance.
        /// </summary>
        /// <param name="reader">An XML reader positioned at the start element. 
        /// The reader should not be advanced.</param>
        /// <returns>true if the ReadKeyIdentifierClause can read the element.</returns>
        public virtual bool CanReadKeyIdentifierClause(XmlReader reader)
        {
            return false;
        }

        /// <summary>
        /// Deserializes the XML to a KeyIdentifierClause that references a token 
        /// handled by this instance.
        /// </summary>
        /// <param name="reader">An XML reader positioned at the KeyIdentifierClause start element.</param>
        /// <returns>SecurityKeyIdentifierClause instance.</returns>
        public virtual SecurityKeyIdentifierClause ReadKeyIdentifierClause(XmlReader reader)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "ReadKeyIdentifierClause")));
        }

        /// <summary>
        /// Indicates if the given SecurityKeyIdentifierClause can be serialized by this
        /// instance.
        /// </summary>
        /// <param name="securityKeyIdentifierClause">SecurityKeyIdentifierClause to be serialized.</param>
        /// <returns>true if the given SecurityKeyIdentifierClause can be serialized.</returns>
        public virtual bool CanWriteKeyIdentifierClause(SecurityKeyIdentifierClause securityKeyIdentifierClause)
        {
            return false;
        }

        /// <summary>
        /// Serializes to XML a SecurityKeyIdentifierClause that this instance supports.
        /// </summary>
        /// <param name="writer">The XML writer.</param>
        /// <param name="securityKeyIdentifierClause">The SecurityKeyIdentifierClause to be used to serialize the token.</param>
        public virtual void WriteKeyIdentifierClause(XmlWriter writer, SecurityKeyIdentifierClause securityKeyIdentifierClause)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "WriteKeyIdentifierClause")));
        }

        /// <summary>
        /// Called by the STS to create a token given a token descriptor. 
        /// </summary>
        /// <param name="tokenDescriptor">Describes the token; properties such 
        /// as ValidFrom, AppliesTo, EncryptingCredentials, Claims, etc., are filled in 
        /// before the call to create token. </param>
        /// <returns>A SecurityToken that matches the properties of the token descriptor.</returns>
        public virtual SecurityToken CreateToken(SecurityTokenDescriptor tokenDescriptor)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "CreateToken")));
        }

        /// <summary>
        /// Creates the security token reference for tokens handled by this instance.
        /// </summary>
        /// <param name="token">The SecurityToken instance for which the references needs to be
        /// created.</param>
        /// <param name="attached">Boolean that indicates if a attached or unattached
        /// reference needs to be created.</param>
        /// <returns>A SecurityKeyIdentifierClause that identifies the given token.</returns>
        public virtual SecurityKeyIdentifierClause CreateSecurityTokenReference(SecurityToken token, bool attached)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "CreateSecurityTokenReference")));
        }

        /// <summary>
        /// The URI used in requests to identify a token of the type handled
        /// by this instance. 
        /// </summary>
        /// <remarks>
        /// For example, this should be the URI value used 
        /// in the RequestSecurityToken's TokenType element to request this
        /// sort of token.
        /// </remarks>
        /// <returns>The set of URIs that identify the token this handler supports.</returns>
        public abstract string[] GetTokenTypeIdentifiers();

        /// <summary>
        /// Validates a <see cref="SecurityToken"/>.
        /// </summary>
        /// <param name="token">The <see cref="SecurityToken"/> to validate.</param>
        /// <returns>The <see cref="ReadOnlyCollection{T}"/> of <see cref="ClaimsIdentity"/> representing the identities contained in the token.</returns>
        /// <remarks>Derived types will validate specific tokens.</remarks>
        public virtual ReadOnlyCollection<ClaimsIdentity> ValidateToken(SecurityToken token)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID4008, "SecurityTokenHandler", "ValidateToken")));
        }

        /// <summary>
        /// Throws if a token is detected as being replayed.
        /// Override this method in your derived class to detect replays.
        /// </summary>
        /// <param name="token">The token to check for replay.</param>
        protected virtual void DetectReplayedToken(SecurityToken token)
        {
        }

        /// <summary>
        /// Load custom configuration from Xml
        /// </summary>
        /// <param name="nodelist">Custom configuration elements</param>
        public virtual void LoadCustomConfiguration(XmlNodeList nodelist)
        {
            throw DiagnosticUtility.ExceptionUtility.ThrowHelperError(new NotImplementedException(SR.GetString(SR.ID0023, this.GetType().AssemblyQualifiedName)));
        }

        protected void TraceTokenValidationSuccess(SecurityToken token)
        {
            if (TD.TokenValidationSuccessIsEnabled())
            {
                TD.TokenValidationSuccess(this.EventTraceActivity, token.GetType().ToString(), token.Id);
            }
        }

        protected void TraceTokenValidationFailure(SecurityToken token, string errorMessage)
        {
            if (TD.TokenValidationFailureIsEnabled())
            {
                TD.TokenValidationFailure(this.EventTraceActivity, token.GetType().ToString(), token.Id, errorMessage);
            }
        }
    }
}