Schematic was introduced in 3.0 as a simple JSON/BSON layer on top of Infinispan. Part of the intent was to utilize the same pattern as Infinispan's AtomicMap, to support delta writes (for state transfer), and to automatically and transparently lock entries as they are modified (rather than manually locking entries prior to modification). The design exposed the SchematicEntry interface representing a value containing a Document (semantically a BSON document that could be written out as JSON). The implementation followed AtomicMap's design by creating a SchematicEntryLiteral that is actually stored as the value in Infinispan and SchematicEntryProxy that was returned to Schematic clients and that facilitated the support for delta writes and automatic locking. Delta writes is the ability for our entries to say what's changed, and then have Infinispan's state transfer ship only that delta (rather than the whole document) to the other processes in the cluster.

However, during the past few years, we've moved completely away from delta writes which, while theoretically making state transfer more efficient, actually was quite problematic. We never really could get Infinispan delta writes to work properly in a clustered environment with eviction enabled (see MODE-1733 and MODE-1745), and so starting in ModeShape 3.1.0.Final we changed our delta implementation to ship the whole document (making in not really a delta) in certain situations, and in finally by ModeShape 3.6 and 3.7 (MODE-2119) we started always using whole deltas for all configurations.

So we're not using deltas anymore, and we have been pre-locking all entries in WritableSessionCache#save(...) methods before that method modifies any of the nodes changed in the Session (see MODE-1821), and we started requiring the Infinispan cache to use PESSIMISTIC locking.

Then, with Infinispan 6.0 the AtomicMap functionality has been deprecated (see the upgrade documentation and mailing list discussion in favor of grouping. Since grouping makes no sense for ModeShape (we're already storing all information about a single node as a single document; we just wanted the ability for changes to be exposed like they were in AtomicMap), there's really no benefit to using AtomicMap anymore and in fact we should move away from it.

So none of the original reasons why we created the current design apply anymore, and in fact the current design (of the proxy and literal and deltas) makes the code more complicated and makes it more difficult to understand what's actually happening in the Infinispan cache (see MODE-2280).

I propose that we simplify Schematic by removing the SchematicEntryProxy and all delta-write functionality. We do need to keep SchematicEntryLiteral because that's the value stored in ModeShape's Infinispan cache. We need to be careful about properly cloning the document before editing (we maybe can change the methods that return an editor) so that we don't edit the same SchematicEntryLiteral instance that is accessible outside of the transaction (remember writes in a txn do not block reads, and Infinispan uses MVCC to isolate changes to an entry during a txn from reads).

If this goes well and especially if this fixes MODE-2280, we should backport this to 3.8.1.Final (and 3.8.1.GA).