Reference[T].cs

Go to the documentation of this file.

using System;
using System.Collections.Generic;
using System.Runtime.Serialization;
 
using AnalyzeRe.APITypes;
using AnalyzeRe.Attributes;
using AnalyzeRe.Utilities;
using RestSharp;
 
// ReSharper disable NonReadonlyMemberInGetHashCode
// We only compute the hashCode the first time it's needed, then never modify it.
// Furthermore, the ref_id of a reference should never be changed after construction,
// it's only modifiable for deserialization purposes.
namespace AnalyzeRe
{
    [APITypeAlias("Reference")]
    public class Reference<T> : Reference, IReference<T> where T : IAPIResource
    {
        #region Private Properties
        private int? _hashCode;
 
        // Stores the object that this reference refers to, if it has been resolved.
        private T _value;
 
        private static readonly string TypeCollectionName;
 
        private readonly string _localCollectionName;
        #endregion Private Properties
 
        #region Public Properties
        [IgnoreDataMember, InternalMember]
        public string CollectionName => _localCollectionName ?? TypeCollectionName;
 
        [IgnoreDataMember, InternalMember]
        public bool resolved { get; private set; }
 
        [IgnoreDataMember, InternalMember]
        public Type ResourceType => _value?.GetType() ?? typeof(T);
 
        [IgnoreDataMember, InternalMember]
        [Obsolete("This property has the potentially unexpected side-effect of resolving the " +
            "reference (an expensive network operation) if it is not already resolved. " +
            "Use the more explicit GetValue() or Resolve() methods instead.")]
        public T Value
        {
            get
            {
                if (!resolved)
                    Resolve();
                return _value;
            }
        }
        #endregion Public Properties
 
        #region Constructors
        static Reference()
        {
            try
            {
                TypeCollectionName = API.GetCollectionName<T>();
            }
            catch (Exception)
            {
                TypeCollectionName = null;
            }
        }
 
        public Reference(string ref_id) : this(ref_id, null) { }
 
        public Reference(string ref_id, string href)
            : base(ref_id, href)
        {
            resolved = false;
            // Hack: ARE-5975: Nested LayerView references must identify their type for
            // "sink" and "sources" references, so that we can distinguish them from layer references.
            // TODO: See if there's a better way to do this only in the context of nested layers.
            reference_type = this is IReference<ILayerView> ? "LayerView" :
                this is IReference<ILayer> ? "Layer" : null;
 
            // Determine the collection name based on the href if one is available.
            if (href == null) return;
            try
            {
                _localCollectionName = API.GetCollectionNameFromResourceHref(href);
            }
            catch (Exception e)
            {
                throw new ArgumentException("The specified href: {href} did not contain a " +
                    "discernible collection name. Expecting something like " +
                    "https://apiurl.net/collection_name/guid", e);
            }
        }
 
        public Reference(IReference other)
            : this(other?.ref_id, other?.href)
        {
            // If the reference being copied matches the current type, check for a resolved value
            if (other is IReference<T> otherTyped)
            {
                if (otherTyped.resolved)
                    TryResolveSelf(otherTyped.GetValue());
            }
            // Otherwise, if the reference being copied has any type and is resolved,
            // copy the resolved value if it can be cast to the current type.
            else if (other is IReference<IAPIResource> otherWeaklyTyped)
            {
                if (otherWeaklyTyped.resolved && otherWeaklyTyped.GetValue() is T asTValue)
                    TryResolveSelf(asTValue);
            }
        }
 
        public Reference(T value) : this(value?.id)
        {
            TryResolveSelf(value);
        }
 
        private bool TryResolveSelf(T value)
        {
            _value = value;
            if (value == null) return false;
            // If our href property isn't set, we can set it now (for convenience)
            if (href == null)
                href = GuessHref(value.id, value);
            resolved = true;
            return true;
        }
        #endregion Constructors
 
        #region Static Methods
        public static string GuessHref(string ref_id, T value = default(T))
        {
            if (TypeCollectionName == null && value == null)
                throw new Exception("Cannot resolve the reference because the collection for " +
                    "resources of type " + typeof(T).NiceTypeName() + " could not be determined " +
                    "and no explicit reference value was provided.");
 
            return String.IsNullOrWhiteSpace(ref_id) ? null : API.ServerURL +
                (value?.collection_name ?? TypeCollectionName) + "/" + ref_id;
        }
        #endregion Static Methods
 
        #region Public Methods
        public T GetValue(IEnumerable<Parameter> requestParameters = null,
            int? timeout = null,
            bool updateCache = false)
        {
            Resolve(requestParameters, timeout, updateCache);
            return _value;
        }
 
        public void Resolve(IEnumerable<Parameter> requestParameters = null,
            int? timeout = null,
            bool updateCache = false)
        {
            // If already resolved, we may not need to do anything
            if (resolved)
            {
                // If updating the cache, use the object's own getter to update it from the server.
                if (updateCache)
                    _value = _value.Get(requestParameters, timeout);
                return;
            }
            // If this reference isn't resolved, determine how best to resolve it.
            string resolvedCollectionName = CollectionName;
            if (resolvedCollectionName == null && href == null)
            {
                throw new Exception("Cannot resolve the reference because " +
                    "the href property has not been set and the collection for " +
                    $"resources of type {typeof(T).NiceTypeName()} could not be determined.");
            }
            // If the reference type is not instantiable, we can determine the expected type
            // based on the href we will resolve the reference with.
            Type expectedType = resolvedCollectionName != null ?
                TypeResolver.ResolveBaseTypeByCollectionName(resolvedCollectionName) :
                TypeResolver.ResolveBaseTypeByURL(href);
 
            // If the type is generic, get the covariant base type that the expected type can be assigned to.
            if (expectedType.IsGenericType)
                expectedType = TypeResolver.GetGenericCovariantBase(expectedType);
 
            // Now we will attempt to retrieve the resource from the server (and deserialize it to the desired type)
            // in the most efficient way possible given the information available.
            T resolvedValue;
 
            // If the expected type is more specific than the current reference class type,
            // supply it as a runtime deserialize type parameter.
            if (typeof(T).IsAssignableFrom(expectedType))
            {
                resolvedValue = resolvedCollectionName != null ?
                    (T)API.RequestAndParse(expectedType, $"{resolvedCollectionName}/{ref_id}",
                        Method.GET, requestParameters, timeout) :
                    (T)API.GetUri(expectedType, new Uri(href), requestParameters, timeout);
            }
            // Otherwise, use the class type and compile-time type parameter invocation.
            else
            {
                resolvedValue = resolvedCollectionName != null ?
                    API.RequestAndParse<T>($"{resolvedCollectionName}/{ref_id}",
                        Method.GET, requestParameters, timeout) :
                    API.GetUri<T>(new Uri(href), requestParameters, timeout);
            }
 
            TryResolveSelf(resolvedValue);
        }
        #endregion Public Methods
 
        #region Equality and Object overrides
        public static explicit operator Reference<T>(T value) => new Reference<T>(value);
 
        public override bool Equals(object obj)
        {
            // If the cast succeeded, we know these two objects share the same collection name
            return obj is IReference<IAPIResource> objReference &&
                // If we reference an object by Id, test that both ids match
                ((ref_id != null && Equals(ref_id, objReference.ref_id) &&
                    Equals(TypeCollectionName, objReference.CollectionName)) ||
                // Otherwise, if both references are resolved, compare embedded values
                (resolved && _value != null && objReference.resolved &&
                    Equals(_value, objReference.GetValue())));
            // TODO: Should two references with a null ref_id and no value be equal?
        }
 
        public override int GetHashCode()
        {
            if (!_hashCode.HasValue)
            {
                // Include the collection name in the hash code to distinguish between
                // resources in different collections with the same UUID (rare)
                _hashCode = ref_id != null ? new { CollectionName, ref_id }.GetHashCode() :
                    // If the value is inlined (no reference id) then derive this
                    // reference's HashCode from the value itself instead.
                    resolved ? new { CollectionName, _value }.GetHashCode() :
                    base.GetHashCode();
            }
            return _hashCode.Value;
        }
 
        public override string ToString()
        {
            return ref_id ?? (resolved ? "new " + _value.GetType().NiceTypeName() : "(empty)");
        }
        #endregion Equality and Object overrides
    }
}