Add keypath filtering to notifications

Realm/Realm/DatabaseTypes/Accessors/ManagedAccessor.cs

@@ -209,7 +209,8 @@ public void UnsubscribeFromNotifications()
         }
 
         /// <inheritdoc/>
-        void INotifiable<NotifiableObjectHandleBase.CollectionChangeSet>.NotifyCallbacks(NotifiableObjectHandleBase.CollectionChangeSet? changes, bool shallow)
+        void INotifiable<NotifiableObjectHandleBase.CollectionChangeSet>.NotifyCallbacks(NotifiableObjectHandleBase.CollectionChangeSet? changes,
+            KeyPathsCollectionType type, IntPtr callback)
         {
             if (changes.HasValue)
             {

Realm/Realm/DatabaseTypes/INotifiable.cs

@@ -33,8 +33,9 @@ internal interface INotifiable<TChangeset>
         /// Method called when there are changes to report for that object.
         /// </summary>
         /// <param name="changes">The changes that occurred.</param>
-        /// <param name="shallow">Whether the changes are coming from a shallow notifier or not.</param>
-        void NotifyCallbacks(TChangeset? changes, bool shallow);
+        /// <param name="type">The type of the key paths collection related to the notification.</param>
+        /// <param name="callbackNative">The eventual callback to call for the notification (if type == Full) </param>
+        void NotifyCallbacks(TChangeset? changes, KeyPathsCollectionType type, IntPtr callbackNative = default);
     }
 
     internal class NotificationToken<TCallback> : IDisposable

Realm/Realm/DatabaseTypes/KeyPathCollection.cs

@@ -0,0 +1,114 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2023 Realm Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+////////////////////////////////////////////////////////////////////////////
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Linq;
+
+namespace Realms;
+
+//TODO Add docs for this and the following types
+public class KeyPathsCollection : IEnumerable<KeyPath>
+{
+    private IEnumerable<KeyPath> _collection;
+
+    private static readonly KeyPathsCollection _shallow = new KeyPathsCollection(KeyPathsCollectionType.Shallow);
+    private static readonly KeyPathsCollection _default = new KeyPathsCollection(KeyPathsCollectionType.Default);
+
+    internal KeyPathsCollectionType Type { get; set; }
+
+    private KeyPathsCollection(KeyPathsCollectionType type, IEnumerable<KeyPath>? collection = null)
+    {
+        Debug.Assert(type == KeyPathsCollectionType.Full == (collection?.Any() == true), "If collection isn't empty, then the type must be Full");
+
+        Type = type;
+        _collection = collection ?? Enumerable.Empty<KeyPath>();
+
+        VerifyKeyPaths();
+    }
+
+    internal IEnumerable<string> GetStrings() => _collection.Select(x => x.Path);
+
+    internal void VerifyKeyPaths()
+    {
+        foreach (var item in _collection)
+        {
+            if (string.IsNullOrWhiteSpace(item?.Path))
+            {
+                throw new ArgumentException("A key path cannot be null, empty, or consisting only of white spaces");
+            }
+        }
+    }
+
+    public static KeyPathsCollection Of(params KeyPath[] paths)
+    {
+        if (paths.Length == 0)
+        {
+            return new KeyPathsCollection(KeyPathsCollectionType.Shallow);
+        }
+
+        return new KeyPathsCollection(KeyPathsCollectionType.Full, paths);
+    }
+
+    public static KeyPathsCollection Shallow => _shallow;
+
+    public static KeyPathsCollection Default => _default;
+
+    public static implicit operator KeyPathsCollection(List<string> paths) =>
+        new(KeyPathsCollectionType.Full, paths.Select(path => (KeyPath)path));
+
+    public static implicit operator KeyPathsCollection(List<KeyPath> paths) => new(KeyPathsCollectionType.Full, paths);
+
+    public static implicit operator KeyPathsCollection(string[] paths) =>
+        new(KeyPathsCollectionType.Full, paths.Select(path => (KeyPath)path));
+
+    public static implicit operator KeyPathsCollection(KeyPath[] paths) => new(KeyPathsCollectionType.Full, paths);
+
+    /// <inheritdoc/>
+    public IEnumerator<KeyPath> GetEnumerator()
+    {
+        return _collection.GetEnumerator();
+    }
+
+    /// <inheritdoc/>
+    IEnumerator IEnumerable.GetEnumerator()
+    {
+        return GetEnumerator();
+    }
+}
+
+public class KeyPath
+{
+    internal string Path { get; private set; }
+
+    private KeyPath(string path)
+    {
+        Path = path;
+    }
+
+    public static implicit operator KeyPath(string s) => new(s);
+}
+
+internal enum KeyPathsCollectionType
+{
+    Default,
+    Shallow,
+    Full
+}

Realm/Realm/DatabaseTypes/RealmCollectionBase.cs

@@ -30,6 +30,7 @@
 using Realms.Exceptions;
 using Realms.Helpers;
 using Realms.Schema;
+using static Realms.NotifiableObjectHandleBase;
 
 namespace Realms
 {
@@ -189,15 +190,41 @@ public IRealmCollection<T> Freeze()
             return CreateCollection(frozenRealm, frozenHandle);
         }
 
-        public IDisposable SubscribeForNotifications(NotificationCallbackDelegate<T> callback)
-            => SubscribeForNotificationsImpl(callback, shallow: false);
+        public IDisposable SubscribeForNotifications(NotificationCallbackDelegate<T> callback, KeyPathsCollection? keyPathCollection = null)
+        {
+            keyPathCollection ??= KeyPathsCollection.Default;
+
+            if (keyPathCollection.Type == KeyPathsCollectionType.Full && !ContainsRealmObjects())
+            {
+                    throw new InvalidOperationException("Key paths can be used only with collections of Realm objects");
+            }
+
+            return SubscribeForNotificationsImpl(callback, keyPathCollection);
+        }
 
-        internal IDisposable SubscribeForNotificationsImpl(NotificationCallbackDelegate<T> callback, bool shallow)
+        internal IDisposable SubscribeForNotificationsImpl(NotificationCallbackDelegate<T> callback, KeyPathsCollection keyPathsCollection)
         {
             Argument.NotNull(callback, nameof(callback));
-            _notificationCallbacks.Value.Add(callback, shallow);
 
-            return NotificationToken.Create(callback, c => UnsubscribeFromNotifications(c, shallow));
+            if (keyPathsCollection.Type == KeyPathsCollectionType.Full)
+            {
+                var managedResultsHandle = GCHandle.Alloc(this, GCHandleType.Weak);
+                var callbackHandle = GCHandle.Alloc(callback, GCHandleType.Weak);
+
+                var token = Handle.Value.AddNotificationCallback(GCHandle.ToIntPtr(managedResultsHandle), keyPathsCollection,
+                    GCHandle.ToIntPtr(callbackHandle));
+
+                return NotificationToken.Create(callback, c => token.Dispose());
+            }
+
+            // For notifications with type Default or Shallow we cache the callbacks on the managed level, to avoid creating multiple notifications in core
+            _notificationCallbacks.Value.Add(callback, keyPathsCollection);
+            return NotificationToken.Create(callback, c => UnsubscribeFromNotifications(c, keyPathsCollection.Type));
+        }
+
+        protected virtual bool ContainsRealmObjects()
+        {
+            return typeof(IRealmObjectBase).IsAssignableFrom(typeof(T));
         }
 
         protected abstract T GetValueAtIndex(int index);
@@ -257,9 +284,9 @@ protected static IEmbeddedObject EnsureUnmanagedEmbedded(in RealmValue value)
             return result;
         }
 
-        private void UnsubscribeFromNotifications(NotificationCallbackDelegate<T> callback, bool shallow)
+        private void UnsubscribeFromNotifications(NotificationCallbackDelegate<T> callback, KeyPathsCollectionType type)
         {
-            _notificationCallbacks.Value.Remove(callback, shallow);
+            _notificationCallbacks.Value.Remove(callback, type);
         }
 
         #region INotifyCollectionChanged
@@ -396,18 +423,31 @@ private void UpdateCollectionChangedSubscriptionIfNecessary(bool isSubscribed)
             {
                 if (isSubscribed)
                 {
-                    SubscribeForNotificationsImpl(OnChange, shallow: true);
+                    SubscribeForNotificationsImpl(OnChange, KeyPathsCollection.Shallow);
                 }
                 else
                 {
-                    UnsubscribeFromNotifications(OnChange, shallow: true);
+                    UnsubscribeFromNotifications(OnChange, KeyPathsCollectionType.Shallow);
                 }
             }
         }
 
         #endregion INotifyCollectionChanged
 
-        void INotifiable<NotifiableObjectHandleBase.CollectionChangeSet>.NotifyCallbacks(NotifiableObjectHandleBase.CollectionChangeSet? changes, bool shallow)
+        void INotifiable<CollectionChangeSet>.NotifyCallbacks(CollectionChangeSet? changes, KeyPathsCollectionType type, IntPtr callbackNative)
+        {
+            if (type == KeyPathsCollectionType.Full
+                && GCHandle.FromIntPtr(callbackNative).Target is NotificationCallbackDelegate<T> callback)
+            {
+                callback(this, GetFromNative(changes));
+                return;
+            }
+
+            var changeset = GetFromNative(changes);
+            _notificationCallbacks.Value.Notify(changeset, type);
+        }
+
+        private ChangeSet? GetFromNative(CollectionChangeSet? changes)
         {
             ChangeSet? changeset = null;
             if (changes != null)
@@ -422,7 +462,7 @@ private void UpdateCollectionChangedSubscriptionIfNecessary(bool isSubscribed)
                     cleared: actualChanges.Cleared);
             }
 
-            _notificationCallbacks.Value.Notify(changeset, shallow);
+            return changeset;
         }
 
         public IEnumerator<T> GetEnumerator() => new Enumerator(this);
@@ -611,19 +651,17 @@ internal class NotificationCallbacks<T>
     {
         private readonly RealmCollectionBase<T> _parent;
 
-        private readonly Dictionary<KeyPath, (NotificationTokenHandle? Token, bool DeliveredInitialNotification, List<NotificationCallbackDelegate<T>> Callbacks)> _subscriptions = new();
+        private readonly Dictionary<KeyPathsCollectionType, (NotificationTokenHandle? Token, bool DeliveredInitialNotification, List<NotificationCallbackDelegate<T>> Callbacks)> _subscriptions = new();
 
         public NotificationCallbacks(RealmCollectionBase<T> parent)
         {
             _parent = parent;
         }
 
-        // Shallow here and everywhere else is a bit of a shortcut we're taking until we have proper keypath filtering.
-        // Once we do, we probably want this to be some keypath identifier that we can pass between managed and native.
-        public void Add(NotificationCallbackDelegate<T> callback, bool shallow)
+        public void Add(NotificationCallbackDelegate<T> callback, KeyPathsCollection keyPathsCollection)
         {
-            var keyPath = shallow ? KeyPath.Empty : KeyPath.Full;
-            if (_subscriptions.TryGetValue(keyPath, out var subscription))
+            var kpcType = keyPathsCollection.Type;
+            if (_subscriptions.TryGetValue(kpcType, out var subscription))
             {
                 if (subscription.DeliveredInitialNotification)
                 {
@@ -638,29 +676,28 @@ public void Add(NotificationCallbackDelegate<T> callback, bool shallow)
             else
             {
                 // If this is a new subscription, we store it in the backing dictionary, then we subscribe outside of transaction
-                _subscriptions[keyPath] = (null, false, new() { callback });
+                _subscriptions[kpcType] = (null, false, new() { callback });
                 _parent.Realm.ExecuteOutsideTransaction(() =>
                 {
                     // It's possible that we unsubscribed in the meantime, so only add a notification callback if we still have callbacks
-                    if (_subscriptions.TryGetValue(keyPath, out var sub) && sub.Callbacks.Count > 0)
+                    if (_subscriptions.TryGetValue(kpcType, out var sub) && sub.Callbacks.Count > 0)
                     {
                         var managedResultsHandle = GCHandle.Alloc(_parent, GCHandleType.Weak);
-                        _subscriptions[keyPath] = (_parent.Handle.Value.AddNotificationCallback(GCHandle.ToIntPtr(managedResultsHandle), shallow), sub.DeliveredInitialNotification, sub.Callbacks);
+                        _subscriptions[kpcType] = (_parent.Handle.Value.AddNotificationCallback(GCHandle.ToIntPtr(managedResultsHandle), keyPathsCollection), sub.DeliveredInitialNotification, sub.Callbacks);
                     }
                 });
             }
         }
 
-        public bool Remove(NotificationCallbackDelegate<T> callback, bool shallow)
+        public bool Remove(NotificationCallbackDelegate<T> callback, KeyPathsCollectionType kpcType)
         {
-            var keyPath = shallow ? KeyPath.Empty : KeyPath.Full;
-            if (_subscriptions.TryGetValue(keyPath, out var subscription))
+            if (_subscriptions.TryGetValue(kpcType, out var subscription))
             {
                 subscription.Callbacks.Remove(callback);
                 if (subscription.Callbacks.Count == 0)
                 {
                     subscription.Token?.Dispose();
-                    _subscriptions.Remove(keyPath);
+                    _subscriptions.Remove(kpcType);
                 }
 
                 return true;
@@ -669,14 +706,13 @@ public bool Remove(NotificationCallbackDelegate<T> callback, bool shallow)
             return false;
         }
 
-        public void Notify(ChangeSet? changes, bool shallow)
+        public void Notify(ChangeSet? changes, KeyPathsCollectionType kpcType)
         {
-            var keyPath = shallow ? KeyPath.Empty : KeyPath.Full;
-            if (_subscriptions.TryGetValue(keyPath, out var subscription))
+            if (_subscriptions.TryGetValue(kpcType, out var subscription))
             {
                 if (changes == null)
                 {
-                    _subscriptions[keyPath] = (subscription.Token, true, subscription.Callbacks);
+                    _subscriptions[kpcType] = (subscription.Token, true, subscription.Callbacks);
                 }
 
                 foreach (var callback in subscription.Callbacks.ToArray())
@@ -695,13 +731,6 @@ public void RemoveAll()
         }
     }
 
-    // Eventually this should be a proper class holding the keypaths
-    internal enum KeyPath
-    {
-        Full,
-        Empty
-    }
-
     /// <summary>
     /// Special invalid object that is used to avoid an exception in WPF
     /// when deleting an element from a collection bound to UI (<see href="https://github.com/realm/realm-dotnet/issues/1903">#1903</see>).

Realm/Realm/DatabaseTypes/RealmDictionary.cs

@@ -243,15 +243,22 @@ private static void ValidateKey(string key)
             }
         }
 
+        protected override bool ContainsRealmObjects()
+        {
+            return typeof(IRealmObjectBase).IsAssignableFrom(typeof(TValue));
+        }
+
         internal override RealmCollectionBase<KeyValuePair<string, TValue>> CreateCollection(Realm realm, CollectionHandleBase handle) => new RealmDictionary<TValue>(realm, (DictionaryHandle)handle, Metadata);
 
         internal override CollectionHandleBase GetOrCreateHandle() => _dictionaryHandle;
 
         protected override KeyValuePair<string, TValue> GetValueAtIndex(int index) => _dictionaryHandle.GetValueAtIndex<TValue>(index, Realm);
 
-        void INotifiable<DictionaryHandle.DictionaryChangeSet>.NotifyCallbacks(DictionaryHandle.DictionaryChangeSet? changes, bool shallow)
+        void INotifiable<DictionaryHandle.DictionaryChangeSet>.NotifyCallbacks(DictionaryHandle.DictionaryChangeSet? changes,
+            KeyPathsCollectionType type, IntPtr callback)
         {
-            Debug.Assert(!shallow, "Shallow should always be false here as we don't expose a way to configure it.");
+            Debug.Assert(type == KeyPathsCollectionType.Default,
+                "Notifications should always be default here as we don't expose a way to configure it.");
 
             DictionaryChangeSet? changeset = null;
             if (changes != null)
@@ -267,9 +274,9 @@ private static void ValidateKey(string key)
                 _deliveredInitialKeyNotification = true;
             }
 
-            foreach (var callback in _keyCallbacks.ToArray())
+            foreach (var keyCallback in _keyCallbacks.ToArray())
             {
-                callback(this, changeset);
+                keyCallback(this, changeset);
             }
         }
     }