You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2026/09/06 22:52:40 UTC

(cayenne) branch master updated: CAY-3015 Get rid of RefreshQuery

This is an automated email from the ASF dual-hosted git repository.

asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git


The following commit(s) were added to refs/heads/master by this push:
     new 271e42d58 CAY-3015 Get rid of RefreshQuery
271e42d58 is described below

commit 271e42d58bfee1e95c261117d6393aa7cb911018
Author: Andrus Adamchik <an...@objectstyle.com>
AuthorDate: Sun Sep 6 18:16:55 2026 -0400

    CAY-3015 Get rid of RefreshQuery
---
 RELEASE-NOTES.txt                                  |   1 +
 UPGRADE.md                                         |  22 ++++
 .../main/java/org/apache/cayenne/DataChannel.java  |  14 +++
 .../java/org/apache/cayenne/ObjectContext.java     |   4 +-
 .../org/apache/cayenne/access/DataContext.java     |  32 ++++-
 .../cayenne/access/DataContextQueryAction.java     | 100 +--------------
 .../java/org/apache/cayenne/access/DataDomain.java |  30 +++++
 .../cayenne/access/DataDomainQueryAction.java      |  89 +-------------
 .../org/apache/cayenne/access/ObjectStore.java     |  20 +++
 .../org/apache/cayenne/query/RefreshQuery.java     | 136 ---------------------
 .../cayenne/CDOCollectionRelationshipIT.java       |   7 +-
 .../org/apache/cayenne/CDOMapRelationshipIT.java   |   7 +-
 .../org/apache/cayenne/CDOSetRelationshipIT.java   |   7 +-
 .../java/org/apache/cayenne/MockDataChannel.java   |   5 +
 .../access/DataContextDecoratedStackIT.java        |   6 +
 ...IT.java => DataContextInvalidateObjectsIT.java} |  70 +++++++----
 .../cayenne/access/DataDomainCallbacksIT.java      |   3 +-
 .../apache/cayenne/query/ObjectSelect_ByIdIT.java  |   2 +-
 .../org/apache/cayenne/query/RefreshQueryTest.java |  96 ---------------
 .../org/apache/cayenne/query/SelectById_RunIT.java |   2 +-
 .../docs/asciidoc/_cayenne-guide/part2/tuning.adoc |   6 +-
 21 files changed, 190 insertions(+), 469 deletions(-)

diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index 6818d5102..cfaf9aaea 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -21,6 +21,7 @@ CAY-3010 LocalDateTime and friends should be accessed directly via JDBC
 CAY-3012 Improve reflection performance
 CAY-3013 MySQL: JDBC-level streaming for iterators
 CAY-3014 Remove QueryChain
+CAY-3015 Get rid of RefreshQuery
 
 Bug Fixes:
 
diff --git a/UPGRADE.md b/UPGRADE.md
index 219860c4c..bff544d0f 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -87,6 +87,28 @@ Expression caseWhenExp = caseWhen(
   });
   ```
 
+*  Per [CAY-3015](https://issues.apache.org/jira/browse/CAY-3015) `org.apache.cayenne.query.RefreshQuery` was removed. It was not a query, but a carrier for 
+   four cache management operations, each of which has a direct replacement:
+
+- `new RefreshQuery(objects)` / `new RefreshQuery(object)` &rarr; `context.invalidateObjects(objects)`. In nested 
+  contexts, there was previously an issue with cascading invalidation (intermediate contexts would not get invalidated).
+  This was fixed in the current version of `invalidateObjects`.
+- `new RefreshQuery("group1", "group2")` &rarr; `runtime.getDataDomain().getQueryCache().removeGroup("group1")`,
+  once per group.
+- `new RefreshQuery(query)` &rarr; run the query itself, with its cache strategy set to `LOCAL_CACHE_REFRESH` or
+  `SHARED_CACHE_REFRESH`. A query with no caching needs no change, as refreshing it was the same as running it:
+
+  ```java
+  ObjectSelect.query(Artist.class)
+          .cacheStrategy(QueryCacheStrategy.SHARED_CACHE_REFRESH)
+          .cacheGroup("artists")
+          .select(context);
+  ```
+
+- `new RefreshQuery()` (refresh everything) has no direct replacement. To start over, create a new
+  `ObjectContext`. To also drop shared state, call `runtime.getDataDomain().getQueryCache().clear()` and
+  `runtime.getDataDomain().getSharedSnapshotCache().clear()`.
+
 *  The `org.apache.cayenne.query.ParameterizedQuery` interface was removed, together with the `createQuery(Map)`
   methods of `SQLTemplate`, `ProcedureQuery` and `ObjectSelect` that implemented it. Applying parameters to a mapped
   query is now the job of the query descriptor - override `QueryDescriptor.buildQuery(Map)` if you have a custom
diff --git a/cayenne/src/main/java/org/apache/cayenne/DataChannel.java b/cayenne/src/main/java/org/apache/cayenne/DataChannel.java
index 52d85205f..e09ac8e62 100644
--- a/cayenne/src/main/java/org/apache/cayenne/DataChannel.java
+++ b/cayenne/src/main/java/org/apache/cayenne/DataChannel.java
@@ -25,6 +25,8 @@ import org.apache.cayenne.graph.GraphDiff;
 import org.apache.cayenne.map.EntityResolver;
 import org.apache.cayenne.query.Query;
 
+import java.util.Collection;
+
 /**
  * DataChannel is an abstraction used by ObjectContexts to obtain mapping metadata and
  * access a persistent store. There is rarely a need to use it directly.
@@ -100,6 +102,18 @@ public interface DataChannel {
      */
     QueryResponse onQuery(ObjectContext originatingContext, Query query, boolean iteratedResult);
 
+    /**
+     * Invalidates objects with the given ids in this channel and all its parents, so that they are refetched on the
+     * next access. In a context, matching registered objects are turned HOLLOW and their uncommitted changes are
+     * discarded. At the root of the channel stack, their snapshots are evicted from the snapshot cache, and peer
+     * contexts are notified via a snapshot event. Objects unknown to a given channel are ignored.
+     *
+     * @param originatingContext an ObjectContext that originated the invalidation.
+     * @param objectIds          ids of the objects to invalidate.
+     * @since 5.0
+     */
+    void onInvalidate(ObjectContext originatingContext, Collection<ObjectId> objectIds);
+
     /**
      * Processes synchronization request from a child ObjectContext, returning a GraphDiff
      * that describes changes to objects made on the receiving end as a result of
diff --git a/cayenne/src/main/java/org/apache/cayenne/ObjectContext.java b/cayenne/src/main/java/org/apache/cayenne/ObjectContext.java
index 866f82161..e59dc931d 100644
--- a/cayenne/src/main/java/org/apache/cayenne/ObjectContext.java
+++ b/cayenne/src/main/java/org/apache/cayenne/ObjectContext.java
@@ -174,9 +174,9 @@ public interface ObjectContext extends DataChannel, Serializable {
      * Executes a selecting query, returning a list of persistent objects or data rows.
      */
     // TODO: this will need to be deprecated at some point. The reason we can't do that yet is that
-    //  EJBQLQuery, SQLTemplate, RefreshQuery, RelationshipQuery, ObjectIdQuery do not implement "Select".
+    //  EJBQLQuery, SQLTemplate, RelationshipQuery, ObjectIdQuery do not implement "Select".
     //  Those queries should eventually either go away (EJBQLQuery, ObjectIdQuery, SQLTemplate) or made implement Select
-    //  (RelationshipQuery, RefreshQuery)
+    //  (RelationshipQuery)
     List performQuery(Query query);
 
     /**
diff --git a/cayenne/src/main/java/org/apache/cayenne/access/DataContext.java b/cayenne/src/main/java/org/apache/cayenne/access/DataContext.java
index a81176a7e..2454c9ba6 100644
--- a/cayenne/src/main/java/org/apache/cayenne/access/DataContext.java
+++ b/cayenne/src/main/java/org/apache/cayenne/access/DataContext.java
@@ -51,7 +51,6 @@ import org.apache.cayenne.query.MappedSelect;
 import org.apache.cayenne.query.ObjectIdQuery;
 import org.apache.cayenne.query.Query;
 import org.apache.cayenne.query.QueryMetadata;
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.query.Select;
 import org.apache.cayenne.reflect.AttributeProperty;
 import org.apache.cayenne.reflect.ClassDescriptor;
@@ -850,8 +849,16 @@ public class DataContext implements ObjectContext {
             throw new NullPointerException("Null collection of objects to invalidate");
         }
 
-        if (!objects.isEmpty()) {
-            performGenericQuery(new RefreshQuery(objects));
+        Collection<ObjectId> ids = new ArrayList<>(objects.size());
+        for (Object object : objects) {
+            Persistent persistent = (Persistent) object;
+            if (persistent.getPersistenceState() != PersistenceState.NEW) {
+                ids.add(persistent.getObjectId());
+            }
+        }
+
+        if (!ids.isEmpty()) {
+            onInvalidate(this, ids);
         }
     }
 
@@ -861,7 +868,24 @@ public class DataContext implements ObjectContext {
     @Override
     public <T> void invalidateObjects(T... objects) {
         if (objects != null && objects.length > 0) {
-            performGenericQuery(new RefreshQuery(Arrays.asList(objects)));
+            invalidateObjects(Arrays.asList(objects));
+        }
+    }
+
+    /**
+     * An implementation of a {@link DataChannel} method that invalidates objects in this context and propagates the
+     * invalidation to the parent channel. Not intended for direct use, call {@link #invalidateObjects(Collection)}
+     * instead.
+     *
+     * @since 5.0
+     */
+    @Override
+    public void onInvalidate(ObjectContext originatingContext, Collection<ObjectId> objectIds) {
+        getObjectStore().objectsInvalidated(objectIds);
+
+        DataChannel parent = getParent();
+        if (parent != null) {
+            parent.onInvalidate(this, objectIds);
         }
     }
 
diff --git a/cayenne/src/main/java/org/apache/cayenne/access/DataContextQueryAction.java b/cayenne/src/main/java/org/apache/cayenne/access/DataContextQueryAction.java
index d84bddb85..05c0ba1d4 100644
--- a/cayenne/src/main/java/org/apache/cayenne/access/DataContextQueryAction.java
+++ b/cayenne/src/main/java/org/apache/cayenne/access/DataContextQueryAction.java
@@ -33,7 +33,6 @@ import org.apache.cayenne.query.ObjectIdQuery;
 import org.apache.cayenne.query.Query;
 import org.apache.cayenne.query.QueryCacheStrategy;
 import org.apache.cayenne.query.QueryMetadata;
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.query.RelationshipQuery;
 import org.apache.cayenne.reflect.ArcProperty;
 import org.apache.cayenne.reflect.ClassDescriptor;
@@ -42,9 +41,7 @@ import org.apache.cayenne.util.ListResponse;
 import org.apache.cayenne.util.ShallowMergeOperation;
 
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.Collections;
-import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -91,10 +88,8 @@ class DataContextQueryAction {
         if (interceptIteratedQuery() != DONE) {
             if (interceptOIDQuery() != DONE) {
                 if (interceptRelationshipQuery() != DONE) {
-                    if (interceptRefreshQuery() != DONE) {
-                        if (interceptLocalCache() != DONE) {
-                            executePostCache();
-                        }
+                    if (interceptLocalCache() != DONE) {
+                        executePostCache();
                     }
                 }
             }
@@ -376,97 +371,6 @@ class DataContextQueryAction {
         return mixedResults;
     }
 
-    protected boolean interceptRefreshQuery() {
-        if (query instanceof RefreshQuery refreshQuery) {
-
-            // handle four separate cases, but do not combine them as it will be
-            // unclear how to handle cascading behavior
-
-            // 1. refresh all
-            if (refreshQuery.isRefreshAll()) {
-                synchronized (actingDataContext.getObjectStore()) {
-
-                    invalidateLocally(actingDataContext.getObjectStore(), actingDataContext
-                            .getObjectStore()
-                            .getObjectIterator());
-
-                    actingDataContext.getQueryCache().clear();
-                }
-
-                // cascade
-                return !DONE;
-            }
-
-            // 2. invalidate object collection
-            Collection<?> objects = refreshQuery.getObjects();
-            if (objects != null && !objects.isEmpty()) {
-
-                synchronized (actingDataContext.getObjectStore()) {
-                    invalidateLocally(actingDataContext.getObjectStore(), objects.iterator());
-                }
-
-                // cascade
-                return !DONE;
-            }
-
-            // 3. refresh query - have to do it eagerly to refresh the objects involved
-            Query cachedQuery = refreshQuery.getQuery();
-            if (cachedQuery != null) {
-
-                String cacheKey = cachedQuery
-                        .getMetaData(actingDataContext.getEntityResolver())
-                        .getCacheKey();
-                actingDataContext.getQueryCache().remove(cacheKey);
-
-                this.response = actingDataContext.performGenericQuery(cachedQuery);
-
-                // do not cascade to avoid running query twice
-                return DONE;
-            }
-
-            // 4. refresh groups...
-            String[] groups = refreshQuery.getGroupKeys();
-            if (groups != null && groups.length > 0) {
-
-                for (String group : groups) {
-                    actingDataContext.getQueryCache().removeGroup(group);
-                }
-
-                // cascade group invalidation
-                return !DONE;
-            }
-
-            // shouldn't ever happen
-            return DONE;
-        }
-
-        return !DONE;
-    }
-
-    private void invalidateLocally(ObjectStore objectStore, Iterator it) {
-        Map<Object, ObjectDiff> diffMap = objectStore.getChangesByObjectId();
-
-        while (it.hasNext()) {
-            Persistent object = (Persistent) it.next();
-
-            int state = object.getPersistenceState();
-
-            // we don't care about NEW objects,
-            // but we still do care about HOLLOW, since snapshot might still
-            // be present
-            if (state == PersistenceState.NEW) {
-                continue;
-            }
-
-            if (state == PersistenceState.MODIFIED || state == PersistenceState.DELETED) {
-                // remove cached changes
-                diffMap.remove(object.getObjectId());
-            }
-
-            object.setPersistenceState(PersistenceState.HOLLOW);
-        }
-    }
-
     protected boolean interceptLocalCache() {
 
         if (metadata.getCacheKey() == null) {
diff --git a/cayenne/src/main/java/org/apache/cayenne/access/DataDomain.java b/cayenne/src/main/java/org/apache/cayenne/access/DataDomain.java
index a43345ea2..d4cc16009 100644
--- a/cayenne/src/main/java/org/apache/cayenne/access/DataDomain.java
+++ b/cayenne/src/main/java/org/apache/cayenne/access/DataDomain.java
@@ -26,6 +26,7 @@ import org.apache.cayenne.DataChannelQueryFilterChain;
 import org.apache.cayenne.DataChannelSyncFilter;
 import org.apache.cayenne.DataChannelSyncFilterChain;
 import org.apache.cayenne.ObjectContext;
+import org.apache.cayenne.ObjectId;
 import org.apache.cayenne.QueryResponse;
 import org.apache.cayenne.access.flush.DataDomainFlushAction;
 import org.apache.cayenne.access.flush.DataDomainFlushActionFactory;
@@ -352,6 +353,35 @@ public class DataDomain implements DataChannel {
         return new DataDomainQueryFilterChain().onQuery(originatingContext, query, iteratedResult);
     }
 
+    /**
+     * Evicts snapshots of the given objects from the snapshot cache, notifying all contexts that share it.
+     *
+     * @since 5.0
+     */
+    @Override
+    public void onInvalidate(ObjectContext originatingContext, Collection<ObjectId> objectIds) {
+        checkStopped();
+
+        if (objectIds.isEmpty()) {
+            return;
+        }
+
+        if (!(originatingContext instanceof DataContext context)) {
+            throw new IllegalArgumentException("DataDomain can only work with DataContext. "
+                    + "Unsupported context type: " + originatingContext);
+        }
+
+        // a context either shares the domain snapshot cache, or has its own
+        DataRowStore snapshotCache = sharedSnapshotCache != null
+                ? sharedSnapshotCache
+                : context.getObjectStore().getDataRowCache();
+
+        if (snapshotCache != null) {
+            snapshotCache.processSnapshotChanges(context.getObjectStore(), Collections.emptyMap(),
+                    Collections.emptyList(), objectIds, Collections.emptyList());
+        }
+    }
+
     QueryResponse onQueryNoFilters(ObjectContext originatingContext, Query query, boolean iteratedResult) {
         // transaction note:
         // we don't wrap this code in transaction to reduce transaction scope to
diff --git a/cayenne/src/main/java/org/apache/cayenne/access/DataDomainQueryAction.java b/cayenne/src/main/java/org/apache/cayenne/access/DataDomainQueryAction.java
index bd664bb2f..1911767ab 100644
--- a/cayenne/src/main/java/org/apache/cayenne/access/DataDomainQueryAction.java
+++ b/cayenne/src/main/java/org/apache/cayenne/access/DataDomainQueryAction.java
@@ -50,7 +50,6 @@ import org.apache.cayenne.query.QueryCacheStrategy;
 import org.apache.cayenne.query.QueryMetadata;
 import org.apache.cayenne.query.QueryMetadataProxy;
 import org.apache.cayenne.query.QueryRouter;
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.query.RelationshipQuery;
 import org.apache.cayenne.reflect.ClassDescriptor;
 import org.apache.cayenne.reflect.DefaultConstructor;
@@ -141,10 +140,8 @@ class DataDomainQueryAction implements QueryRouter, OperationObserver {
         if (interceptIteratedQuery() != DONE) {
             if (interceptOIDQuery() != DONE) {
                 if (interceptRelationshipQuery() != DONE) {
-                    if (interceptRefreshQuery() != DONE) {
-                        if (interceptSharedCache() != DONE) {
-                            runQueryInTransaction();
-                        }
+                    if (interceptSharedCache() != DONE) {
+                        runQueryInTransaction();
                     }
                 }
             }
@@ -354,88 +351,6 @@ class DataDomainQueryAction implements QueryRouter, OperationObserver {
         return !DONE;
     }
 
-    /**
-     * @since 3.0
-     */
-    @SuppressWarnings("deprecation")
-    private boolean interceptRefreshQuery() {
-
-        if (query instanceof RefreshQuery refreshQuery) {
-
-            if (refreshQuery.isRefreshAll()) {
-
-                // not sending any events - peer contexts will not get refreshed
-                if (domain.getSharedSnapshotCache() != null) {
-                    domain.getSharedSnapshotCache().clear();
-                } else {
-                    // remove snapshots from local ObjectStore only
-                    context.getObjectStore().getDataRowCache().clear();
-                }
-                context.getQueryCache().clear();
-
-                GenericResponse response = new GenericResponse();
-                response.addUpdateCount(1);
-                this.response = response;
-                return DONE;
-            }
-
-            @SuppressWarnings("unchecked")
-            Collection<Persistent> objects = (Collection<Persistent>) refreshQuery.getObjects();
-            if (objects != null && !objects.isEmpty()) {
-
-                Collection<ObjectId> ids = new ArrayList<>(objects.size());
-                for (final Persistent object : objects) {
-                    ids.add(object.getObjectId());
-                }
-
-                if (domain.getSharedSnapshotCache() != null) {
-                    // send an event for removed snapshots
-                    domain.getSharedSnapshotCache().processSnapshotChanges(context.getObjectStore(),
-                            Collections.emptyMap(), Collections.emptyList(), ids, Collections.emptyList());
-                } else {
-                    // remove snapshots from local ObjectStore only
-                    context.getObjectStore()
-                            .getDataRowCache()
-                            .processSnapshotChanges(context.getObjectStore(), Collections.emptyMap(),
-                                    Collections.emptyList(), ids, Collections.emptyList());
-                }
-
-                GenericResponse response = new GenericResponse();
-                response.addUpdateCount(1);
-                this.response = response;
-                return DONE;
-            }
-
-            // 3. refresh query - this shouldn't normally happen as child context
-            // usually does a cascading refresh
-            if (refreshQuery.getQuery() != null) {
-                Query cachedQuery = refreshQuery.getQuery();
-
-                String cacheKey = cachedQuery.getMetaData(context.getEntityResolver()).getCacheKey();
-                context.getQueryCache().remove(cacheKey);
-
-                this.response = domain.onQuery(context, cachedQuery, false);
-                return DONE;
-            }
-
-            // 4. refresh groups...
-            if (refreshQuery.getGroupKeys() != null && refreshQuery.getGroupKeys().length > 0) {
-
-                String[] groups = refreshQuery.getGroupKeys();
-                for (String group : groups) {
-                    domain.getQueryCache().removeGroup(group);
-                }
-
-                GenericResponse response = new GenericResponse();
-                response.addUpdateCount(1);
-                this.response = response;
-                return DONE;
-            }
-        }
-
-        return !DONE;
-    }
-
     /*
      * Wraps execution in shared cache checks
      */
diff --git a/cayenne/src/main/java/org/apache/cayenne/access/ObjectStore.java b/cayenne/src/main/java/org/apache/cayenne/access/ObjectStore.java
index 182902fbc..67fec89d5 100644
--- a/cayenne/src/main/java/org/apache/cayenne/access/ObjectStore.java
+++ b/cayenne/src/main/java/org/apache/cayenne/access/ObjectStore.java
@@ -288,6 +288,26 @@ public class ObjectStore implements Serializable, SnapshotEventListener, GraphMa
         dataRowCacheSet = dataRowCache != null;
     }
 
+    /**
+     * Turns registered objects with the given ids HOLLOW, discarding their uncommitted changes. Ids of unregistered
+     * or NEW objects are ignored. Does not touch the snapshot cache.
+     *
+     * @since 5.0
+     */
+    synchronized void objectsInvalidated(Collection<ObjectId> ids) {
+        for (ObjectId id : ids) {
+            Persistent object = (Persistent) objectMap.get(id);
+
+            // NEW objects have nothing to refetch. HOLLOW objects are still processed, as they may have pending changes
+            if (object == null || object.getPersistenceState() == PersistenceState.NEW) {
+                continue;
+            }
+
+            changes.remove(id);
+            object.setPersistenceState(PersistenceState.HOLLOW);
+        }
+    }
+
     /**
      * Evicts a collection of Persistent objects from the ObjectStore, invalidates the underlying
      * cache snapshots. Changes objects state to TRANSIENT. This method can be used for
diff --git a/cayenne/src/main/java/org/apache/cayenne/query/RefreshQuery.java b/cayenne/src/main/java/org/apache/cayenne/query/RefreshQuery.java
deleted file mode 100644
index 32ff343c7..000000000
--- a/cayenne/src/main/java/org/apache/cayenne/query/RefreshQuery.java
+++ /dev/null
@@ -1,136 +0,0 @@
-/*****************************************************************
- *   Licensed to the Apache Software Foundation (ASF) under one
- *  or more contributor license agreements.  See the NOTICE file
- *  distributed with this work for additional information
- *  regarding copyright ownership.  The ASF licenses this file
- *  to you 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
- *
- *    https://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.
- ****************************************************************/
-package org.apache.cayenne.query;
-
-import org.apache.cayenne.CayenneRuntimeException;
-import org.apache.cayenne.Persistent;
-import org.apache.cayenne.map.EntityResolver;
-
-import java.util.Collection;
-import java.util.Collections;
-
-/**
- * A query that allows to explicitly clear both object and list caches either via refetch
- * (eager refresh) or invalidate (lazy refresh).
- *
- * @since 3.0
- */
-public class RefreshQuery implements Query {
-
-    protected Collection<?> objects;
-    protected Query query;
-    protected String[] groupKeys;
-
-    /**
-     * Creates a RefreshQuery that refreshes a collection of objects, including
-     * invalidation of their relationships.
-     */
-    public RefreshQuery(Collection<?> objects) {
-        this.objects = objects;
-    }
-
-    /**
-     * Creates a RefreshQuery that refreshes a single object, including invalidation of
-     * its relationships.
-     */
-    public RefreshQuery(Persistent object) {
-        this(Collections.singletonList(object));
-    }
-
-    /**
-     * Creates a RefreshQuery that refreshes results of a query and individual objects in
-     * the result.
-     */
-    public RefreshQuery(Query query) {
-        this.query = query;
-    }
-
-    /**
-     * Creates a RefreshQuery that refreshes query results identified by group keys.
-     */
-    public RefreshQuery(String... groupKeys) {
-        this.groupKeys = groupKeys != null && groupKeys.length == 0 ? null : groupKeys;
-    }
-
-    public QueryMetadata getMetaData(EntityResolver resolver) {
-        return new BaseQueryMetadata();
-    }
-
-    public void route(QueryRouter router, EntityResolver resolver, Query substitutedQuery) {
-        // noop
-    }
-
-    public SQLAction createSQLAction(SQLActionVisitor visitor) {
-        throw new CayenneRuntimeException("Unsupported operation");
-    }
-
-    public boolean isRefreshAll() {
-        return objects == null && query == null && groupKeys == null;
-    }
-
-    public String[] getGroupKeys() {
-        return groupKeys;
-    }
-
-    public Collection<?> getObjects() {
-        return objects;
-    }
-
-    /**
-     * Returns an internal query, overriding cache policy to force a refresh. Returns null
-     * if no query was set.
-     */
-    public Query getQuery() {
-
-        if (query == null) {
-            return null;
-        }
-
-        return new Query() {
-
-            public SQLAction createSQLAction(SQLActionVisitor visitor) {
-                throw new CayenneRuntimeException("Unsupported");
-            }
-
-            public QueryMetadata getMetaData(EntityResolver resolver) {
-                QueryMetadata md = query.getMetaData(resolver);
-                QueryCacheStrategy refreshStrategy = switch (md.getCacheStrategy()) {
-                    case LOCAL_CACHE -> QueryCacheStrategy.LOCAL_CACHE_REFRESH;
-                    case SHARED_CACHE -> QueryCacheStrategy.SHARED_CACHE_REFRESH;
-                    case null, default -> md.getCacheStrategy();
-                };
-
-                return new QueryMetadataProxy(md) {
-                    @Override
-                    public QueryCacheStrategy getCacheStrategy() {
-                        return refreshStrategy;
-                    }
-                };
-            }
-
-            public void route(
-                    QueryRouter router,
-                    EntityResolver resolver,
-                    Query substitutedQuery) {
-                query.route(router, resolver, this);
-            }
-        };
-    }
-
-}
diff --git a/cayenne/src/test/java/org/apache/cayenne/CDOCollectionRelationshipIT.java b/cayenne/src/test/java/org/apache/cayenne/CDOCollectionRelationshipIT.java
index 0e5a5967f..d1a652d00 100644
--- a/cayenne/src/test/java/org/apache/cayenne/CDOCollectionRelationshipIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/CDOCollectionRelationshipIT.java
@@ -20,7 +20,6 @@ package org.apache.cayenne;
 
 import org.apache.cayenne.exp.ExpressionFactory;
 import org.apache.cayenne.query.ObjectSelect;
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.test.jdbc.TableHelper;
 import org.apache.cayenne.testdo.relationships_collection_to_many.CollectionToMany;
 import org.apache.cayenne.testdo.relationships_collection_to_many.CollectionToManyTarget;
@@ -128,7 +127,7 @@ public class CDOCollectionRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(4, o1.getTargets().size());
     }
 
@@ -152,7 +151,7 @@ public class CDOCollectionRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(2, o1.getTargets().size());
         assertFalse(o1.getTargets().contains(target));
     }
@@ -176,7 +175,7 @@ public class CDOCollectionRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(4, o1.getTargets().size());
     }
 }
diff --git a/cayenne/src/test/java/org/apache/cayenne/CDOMapRelationshipIT.java b/cayenne/src/test/java/org/apache/cayenne/CDOMapRelationshipIT.java
index 2e6c65946..48bd0e4de 100644
--- a/cayenne/src/test/java/org/apache/cayenne/CDOMapRelationshipIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/CDOMapRelationshipIT.java
@@ -20,7 +20,6 @@ package org.apache.cayenne;
 
 import java.util.Map;
 
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.query.ObjectSelect;
 import org.apache.cayenne.test.jdbc.TableHelper;
 import org.apache.cayenne.testdo.map_to_many.IdMapToMany;
@@ -159,7 +158,7 @@ public class CDOMapRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(4, o1.getTargets().size());
     }
 
@@ -181,7 +180,7 @@ public class CDOMapRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(2, o1.getTargets().size());
         assertNotNull(o1.getTargets().get("A"));
         assertNotNull(o1.getTargets().get("C"));
@@ -209,7 +208,7 @@ public class CDOMapRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(4, o1.getTargets().size());
     }
 
diff --git a/cayenne/src/test/java/org/apache/cayenne/CDOSetRelationshipIT.java b/cayenne/src/test/java/org/apache/cayenne/CDOSetRelationshipIT.java
index 18766e6ef..808958e23 100644
--- a/cayenne/src/test/java/org/apache/cayenne/CDOSetRelationshipIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/CDOSetRelationshipIT.java
@@ -18,7 +18,6 @@
  ****************************************************************/
 package org.apache.cayenne;
 
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.query.ObjectSelect;
 import org.apache.cayenne.test.jdbc.TableHelper;
 import org.apache.cayenne.testdo.relationships_set_to_many.SetToMany;
@@ -138,7 +137,7 @@ public class CDOSetRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(4, o1.getTargets().size());
     }
 
@@ -163,7 +162,7 @@ public class CDOSetRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(2, o1.getTargets().size());
         assertFalse(o1.getTargets().contains(target));
     }
@@ -189,7 +188,7 @@ public class CDOSetRelationshipIT {
 
         o1.getObjectContext().commitChanges();
 
-        o1.getObjectContext().performGenericQuery(new RefreshQuery());
+        o1.getObjectContext().invalidateObjects(o1);
         assertEquals(4, o1.getTargets().size());
     }
 
diff --git a/cayenne/src/test/java/org/apache/cayenne/MockDataChannel.java b/cayenne/src/test/java/org/apache/cayenne/MockDataChannel.java
index 26daf5ab6..e9deeb8db 100644
--- a/cayenne/src/test/java/org/apache/cayenne/MockDataChannel.java
+++ b/cayenne/src/test/java/org/apache/cayenne/MockDataChannel.java
@@ -20,6 +20,7 @@
 package org.apache.cayenne;
 
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.List;
 
 import org.apache.cayenne.DataChannel;
@@ -94,6 +95,10 @@ public class MockDataChannel implements DataChannel {
         return response;
     }
 
+    public void onInvalidate(ObjectContext originatingContext, Collection<ObjectId> objectIds) {
+        requestObjects.add(objectIds);
+    }
+
     public EntityResolver getEntityResolver() {
         return resolver;
     }
diff --git a/cayenne/src/test/java/org/apache/cayenne/access/DataContextDecoratedStackIT.java b/cayenne/src/test/java/org/apache/cayenne/access/DataContextDecoratedStackIT.java
index a352e0d02..ae03d438a 100644
--- a/cayenne/src/test/java/org/apache/cayenne/access/DataContextDecoratedStackIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/access/DataContextDecoratedStackIT.java
@@ -21,6 +21,7 @@ package org.apache.cayenne.access;
 import org.apache.cayenne.Cayenne;
 import org.apache.cayenne.DataChannel;
 import org.apache.cayenne.ObjectContext;
+import org.apache.cayenne.ObjectId;
 import org.apache.cayenne.QueryResponse;
 import org.apache.cayenne.dba.frontbase.FrontBaseAdapter;
 import org.apache.cayenne.dba.mysql.MySQLAdapter;
@@ -35,6 +36,7 @@ import org.apache.cayenne.unit.CayenneTestsEnv;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 
+import java.util.Collection;
 import java.util.Map;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -111,6 +113,10 @@ public class DataContextDecoratedStackIT {
             return channel.onSync(originatingContext, changes, syncType);
         }
 
+        public void onInvalidate(ObjectContext originatingContext, Collection<ObjectId> objectIds) {
+            channel.onInvalidate(originatingContext, objectIds);
+        }
+
         public DataChannel getParent() {
             return channel;
         }
diff --git a/cayenne/src/test/java/org/apache/cayenne/access/DataContextRefreshQueryIT.java b/cayenne/src/test/java/org/apache/cayenne/access/DataContextInvalidateObjectsIT.java
similarity index 87%
rename from cayenne/src/test/java/org/apache/cayenne/access/DataContextRefreshQueryIT.java
rename to cayenne/src/test/java/org/apache/cayenne/access/DataContextInvalidateObjectsIT.java
index d26f25625..17c6e5415 100644
--- a/cayenne/src/test/java/org/apache/cayenne/access/DataContextRefreshQueryIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/access/DataContextInvalidateObjectsIT.java
@@ -21,11 +21,11 @@ package org.apache.cayenne.access;
 import java.util.List;
 
 import org.apache.cayenne.Cayenne;
+import org.apache.cayenne.ObjectContext;
 import org.apache.cayenne.PersistenceState;
 import org.apache.cayenne.ValueHolder;
 import org.apache.cayenne.query.ObjectSelect;
 import org.apache.cayenne.query.QueryCacheStrategy;
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.query.SortOrder;
 import org.apache.cayenne.test.jdbc.TableHelper;
 import org.apache.cayenne.testdo.testmap.Artist;
@@ -38,7 +38,7 @@ import org.junit.jupiter.api.Test;
 
 import static org.junit.jupiter.api.Assertions.*;
 
-public class DataContextRefreshQueryIT  {
+public class DataContextInvalidateObjectsIT {
 
     @RegisterExtension
     static final CayenneTestsEnv env = CayenneTestsEnv.forProject(CayenneProjects.TESTMAP_PROJECT);
@@ -83,7 +83,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshCollection() throws Exception {
+    public void invalidateCollection() throws Exception {
         createRefreshCollectionDataSet();
 
         List<Artist> artists = ObjectSelect.query(Artist.class)
@@ -105,8 +105,7 @@ public class DataContextRefreshQueryIT  {
                 .getSharedSnapshotCache()
                 .getCachedSnapshot(a2.getObjectId()));
 
-        RefreshQuery refresh = new RefreshQuery(artists);
-        context.performQuery(refresh);
+        context.invalidateObjects(artists);
 
         assertNull(context
                 .getParentDataDomain()
@@ -127,7 +126,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshCollectionToOne() throws Exception {
+    public void invalidateCollectionToOne() throws Exception {
         createRefreshCollectionDataSet();
 
         List<Painting> paints = ObjectSelect.query(Painting.class)
@@ -151,8 +150,7 @@ public class DataContextRefreshQueryIT  {
 
         createRefreshCollectionToOneUpdateDataSet();
 
-        RefreshQuery refresh = new RefreshQuery(paints);
-        context.performQuery(refresh);
+        context.invalidateObjects(paints);
 
         assertNull(context
                 .getParentDataDomain()
@@ -172,7 +170,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshSingleObject() throws Exception {
+    public void invalidateSingleObject() throws Exception {
         createRefreshCollectionDataSet();
 
         List<Artist> artists = ObjectSelect.query(Artist.class)
@@ -188,8 +186,7 @@ public class DataContextRefreshQueryIT  {
                 .getSharedSnapshotCache()
                 .getCachedSnapshot(a1.getObjectId()));
 
-        RefreshQuery refresh = new RefreshQuery(a1);
-        context.performQuery(refresh);
+        context.invalidateObjects(a1);
 
         assertNull(context
                 .getParentDataDomain()
@@ -203,7 +200,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshObjectToMany() throws Exception {
+    public void invalidateObjectToMany() throws Exception {
         createRefreshObjectToManyDataSet();
 
         Artist a = Cayenne.objectForPK(context, Artist.class, 33001L);
@@ -211,14 +208,13 @@ public class DataContextRefreshQueryIT  {
 
         createRefreshObjectToManyUpdateDataSet();
 
-        RefreshQuery refresh = new RefreshQuery(a);
-        context.performQuery(refresh);
+        context.invalidateObjects(a);
         assertEquals(PersistenceState.HOLLOW, a.getPersistenceState());
         assertEquals(1, a.getPaintingArray().size());
     }
 
     @Test
-    public void refreshQueryResultsLocalCache() throws Exception {
+    public void localCacheRefresh() throws Exception {
         createRefreshCollectionDataSet();
 
         ObjectSelect<Painting> q = ObjectSelect.query(Painting.class)
@@ -248,8 +244,7 @@ public class DataContextRefreshQueryIT  {
 
         createRefreshCollectionToOneUpdateDataSet();
 
-        RefreshQuery refresh = new RefreshQuery(q);
-        context.performQuery(refresh);
+        q.cacheStrategy(QueryCacheStrategy.LOCAL_CACHE_REFRESH).select(context);
 
         assertNotNull(context
                 .getParentDataDomain()
@@ -272,7 +267,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshQueryResultsSharedCache() throws Exception {
+    public void sharedCacheRefresh() throws Exception {
         createRefreshCollectionDataSet();
 
         ObjectSelect<Painting> q = ObjectSelect.query(Painting.class)
@@ -301,8 +296,7 @@ public class DataContextRefreshQueryIT  {
 
         createRefreshCollectionToOneUpdateDataSet();
 
-        RefreshQuery refresh = new RefreshQuery(q);
-        context.performQuery(refresh);
+        q.cacheStrategy(QueryCacheStrategy.SHARED_CACHE_REFRESH).select(context);
 
         assertNotNull(context
                 .getParentDataDomain()
@@ -325,7 +319,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshQueryResultGroupLocal() throws Exception {
+    public void removeCacheGroupLocal() throws Exception {
         createRefreshCollectionDataSet();
 
         ObjectSelect<Painting> q = ObjectSelect.query(Painting.class)
@@ -361,10 +355,8 @@ public class DataContextRefreshQueryIT  {
         assertEquals("c", p1.getToArtist().getArtistName());
         assertEquals("c", p2.getToArtist().getArtistName());
 
-        RefreshQuery refresh = new RefreshQuery("X");
-
         // this should invalidate results for the next query run
-        context.performQuery(refresh);
+        context.getParentDataDomain().getQueryCache().removeGroup("X");
 
         // this should force a refresh
         context.performQuery(q);
@@ -379,7 +371,7 @@ public class DataContextRefreshQueryIT  {
     }
 
     @Test
-    public void refreshAll() throws Exception {
+    public void invalidateAllRegistered() throws Exception {
         createRefreshCollectionDataSet();
         ObjectSelect<Artist> q = ObjectSelect.query(Artist.class)
                 .orderBy("db:ARTIST_ID", SortOrder.ASCENDING);
@@ -407,8 +399,7 @@ public class DataContextRefreshQueryIT  {
                 .getSharedSnapshotCache()
                 .getCachedSnapshot(p2.getObjectId()));
 
-        RefreshQuery refresh = new RefreshQuery();
-        context.performQuery(refresh);
+        context.invalidateObjects(context.getObjectStore().registeredNodes());
 
         assertNull(context
                 .getParentDataDomain()
@@ -432,4 +423,29 @@ public class DataContextRefreshQueryIT  {
         assertEquals(PersistenceState.HOLLOW, p1.getPersistenceState());
         assertEquals(PersistenceState.HOLLOW, p2.getPersistenceState());
     }
+
+    @Test
+    public void invalidateFromChildContext() throws Exception {
+        createRefreshCollectionDataSet();
+
+        Artist parentArtist = Cayenne.objectForPK(context, Artist.class, 33001);
+        parentArtist.setArtistName("modified in parent");
+        assertEquals(PersistenceState.MODIFIED, parentArtist.getPersistenceState());
+
+        ObjectContext child = env.runtime().newContext(context);
+        Artist childArtist = Cayenne.objectForPK(child, Artist.class, 33001);
+        assertNotSame(parentArtist, childArtist);
+
+        child.invalidateObjects(childArtist);
+
+        assertEquals(PersistenceState.HOLLOW, childArtist.getPersistenceState());
+        assertEquals(PersistenceState.HOLLOW, parentArtist.getPersistenceState());
+        assertFalse(context.hasChanges());
+        assertNull(context
+                .getParentDataDomain()
+                .getSharedSnapshotCache()
+                .getCachedSnapshot(parentArtist.getObjectId()));
+
+        assertEquals("c", parentArtist.getArtistName());
+    }
 }
diff --git a/cayenne/src/test/java/org/apache/cayenne/access/DataDomainCallbacksIT.java b/cayenne/src/test/java/org/apache/cayenne/access/DataDomainCallbacksIT.java
index a0cbbceba..8401af64b 100644
--- a/cayenne/src/test/java/org/apache/cayenne/access/DataDomainCallbacksIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/access/DataDomainCallbacksIT.java
@@ -25,7 +25,6 @@ import org.apache.cayenne.map.EntityResolver;
 import org.apache.cayenne.map.LifecycleEvent;
 import org.apache.cayenne.query.EJBQLQuery;
 import org.apache.cayenne.query.ObjectSelect;
-import org.apache.cayenne.query.RefreshQuery;
 import org.apache.cayenne.reflect.LifecycleCallbackRegistry;
 import org.apache.cayenne.testdo.testmap.Artist;
 import org.apache.cayenne.testdo.testmap.Painting;
@@ -96,7 +95,7 @@ public class DataDomainCallbacksIT {
         assertEquals(0, a1.getPostLoaded());
         assertNull(listener.getPublicCalledbackEntity());
 
-        env.context().performQuery(new RefreshQuery(a1));
+        env.context().invalidateObjects(a1);
         assertEquals(0, a1.getPostLoaded());
         assertNull(listener.getPublicCalledbackEntity());
 
diff --git a/cayenne/src/test/java/org/apache/cayenne/query/ObjectSelect_ByIdIT.java b/cayenne/src/test/java/org/apache/cayenne/query/ObjectSelect_ByIdIT.java
index ab3509a11..f648c0a21 100644
--- a/cayenne/src/test/java/org/apache/cayenne/query/ObjectSelect_ByIdIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/query/ObjectSelect_ByIdIT.java
@@ -261,7 +261,7 @@ public class ObjectSelect_ByIdIT {
             assertSame(a3[0], a3cached);
         });
 
-        env.context().performGenericQuery(new RefreshQuery("g1"));
+        env.runtime().getDataDomain().getQueryCache().removeGroup("g1");
 
         assertEquals(1, env.runWithQueryCounter(() -> ObjectSelect.query(Artist.class)
                 .where(Artist.SELF.eqId(3)).localCache("g1").selectOne(env.context())));
diff --git a/cayenne/src/test/java/org/apache/cayenne/query/RefreshQueryTest.java b/cayenne/src/test/java/org/apache/cayenne/query/RefreshQueryTest.java
deleted file mode 100644
index 32ea8e281..000000000
--- a/cayenne/src/test/java/org/apache/cayenne/query/RefreshQueryTest.java
+++ /dev/null
@@ -1,96 +0,0 @@
-/*****************************************************************
- *   Licensed to the Apache Software Foundation (ASF) under one
- *  or more contributor license agreements.  See the NOTICE file
- *  distributed with this work for additional information
- *  regarding copyright ownership.  The ASF licenses this file
- *  to you 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
- *
- *    https://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.
- ****************************************************************/
-package org.apache.cayenne.query;
-
-import org.apache.cayenne.MockPersistentObject;
-import org.apache.cayenne.Persistent;
-import org.junit.jupiter.api.Test;
-
-import java.util.ArrayList;
-import java.util.Collection;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertNotNull;
-import static org.junit.jupiter.api.Assertions.assertNotSame;
-import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertSame;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-public class RefreshQueryTest {
-
-    @Test
-    public void refreshAllConstructor() {
-
-        RefreshQuery q = new RefreshQuery();
-        assertNull(q.getObjects());
-        assertNull(q.getQuery());
-        assertNull(q.getGroupKeys());
-        assertTrue(q.isRefreshAll());
-    }
-
-    @Test
-    public void collectionConstructor() {
-        Collection c = new ArrayList();
-        c.add(new Object());
-        c.add(new Object());
-
-        RefreshQuery q = new RefreshQuery(c);
-        assertSame(c, q.getObjects());
-        assertNull(q.getQuery());
-        assertNull(q.getGroupKeys());
-        assertFalse(q.isRefreshAll());
-    }
-
-    @Test
-    public void objectConstructor() {
-        Persistent p = new MockPersistentObject();
-
-        RefreshQuery q = new RefreshQuery(p);
-        assertNotNull(q.getObjects());
-        assertEquals(1, q.getObjects().size());
-        assertSame(p, q.getObjects().iterator().next());
-        assertNull(q.getQuery());
-        assertNull(q.getGroupKeys());
-        assertFalse(q.isRefreshAll());
-    }
-
-    @Test
-    public void queryConstructor() {
-        Query query = new MockQuery();
-
-        RefreshQuery q = new RefreshQuery(query);
-        assertNull(q.getObjects());
-        assertNotNull(q.getQuery());
-        assertNotSame(query, q.getQuery(), "query must be wrapped");
-        assertNull(q.getGroupKeys());
-        assertFalse(q.isRefreshAll());
-    }
-
-    @Test
-    public void groupKeysConstructor() {
-        String[] groupKeys = new String[] { "a", "b" };
-
-        RefreshQuery q = new RefreshQuery(groupKeys);
-        assertNull(q.getObjects());
-        assertNull(q.getQuery());
-        assertSame(groupKeys, q.getGroupKeys());
-    }
-
-}
diff --git a/cayenne/src/test/java/org/apache/cayenne/query/SelectById_RunIT.java b/cayenne/src/test/java/org/apache/cayenne/query/SelectById_RunIT.java
index 5a7605861..1259a4603 100644
--- a/cayenne/src/test/java/org/apache/cayenne/query/SelectById_RunIT.java
+++ b/cayenne/src/test/java/org/apache/cayenne/query/SelectById_RunIT.java
@@ -421,7 +421,7 @@ public class SelectById_RunIT {
             assertSame(a3[0], a3cached);
         });
 
-        env.context().performGenericQuery(new RefreshQuery("g1"));
+        env.runtime().getDataDomain().getQueryCache().removeGroup("g1");
 
         assertEquals(1, env.runWithQueryCounter(() ->
                 SelectById.queryId(Artist.class, 3).localCache("g1").selectOne(env.context())));
diff --git a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
index ea6c2b9ba..aa6a40bc8 100644
--- a/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
+++ b/docs/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/tuning.adoc
@@ -304,12 +304,12 @@ expiration policies, etc. For the managed cache, you will need to explicitly use
 Use can use <<ext-jcache,JCache integration module>> to enable any of JCache API compatible caching providers.
 
 Often "passive" cache expiration policies used by caching providers are not sufficient, and the users want real-time cache invalidation when the data changes.
-So in addition to those policies, the app can invalidate individual cache groups explicitly with `RefreshQuery`:
+So in addition to those policies, the app can invalidate individual cache groups explicitly via `QueryCache`:
 
 [source, Java]
 ----
-RefreshQuery refresh = new RefreshQuery("artist");
-context.performGenericQuery(refresh);
+QueryCache cache = runtime.getDataDomain().getQueryCache();
+cache.removeGroup("artist");
 ----
 
 The above can be used e.g. to build UI for manual cache invalidation.