ContextRemover.java
/*
* Copyright (c) 2007-2026 MetaSolutions AB
*
* 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.
*/
package org.entrystore.impl;
import lombok.extern.slf4j.Slf4j;
import org.eclipse.rdf4j.model.IRI;
import org.eclipse.rdf4j.model.Resource;
import org.eclipse.rdf4j.model.Statement;
import org.eclipse.rdf4j.repository.Repository;
import org.eclipse.rdf4j.repository.RepositoryConnection;
import org.eclipse.rdf4j.repository.RepositoryResult;
import org.eclipse.rdf4j.repository.sparql.SPARQLRepository;
import org.entrystore.Entry;
import org.entrystore.SearchIndex;
import org.entrystore.repository.config.Settings;
import org.entrystore.repository.util.URISplit;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.nio.file.DirectoryNotEmptyException;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.RejectedExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.function.Consumer;
import java.util.function.Supplier;
import static org.eclipse.rdf4j.model.util.Values.iri;
/**
* Deletes the graphs, search documents and files of removed contexts in the background.
*
* <p>Removing a context only takes its entry out of {@code _contexts} and records a
* {@link RepositoryProperties#removalPending} marker, in one short transaction. This job then deletes every graph
* named {@code {base}{contextId}} or starting with {@code {base}{contextId}/}, in chunks of {@link #chunkSize}
* statements. A chunk is read without a transaction or the repository monitor and removed in a transaction of
* its own under the monitor, so other writers wait for one chunk at most. Each statement is removed by its whole
* triple within its graph, which any triple index finds without a scan (on a SPARQL store, with wildcards for its
* blank nodes); reading a graph scans the store unless the store has an index starting with the context.
*
* <p>Statements of the context whose object is an entry of another context may have a copy in that entry's
* relations graph. The copy is removed with them, unless a graph outside the context, other than a relations
* graph, still states the triple; see {@link ExactRemoval}.
*
* <p>The marker survives a restart, after which {@link #resumePending()} continues the job. A job that fails
* stops and keeps the marker, so the context stays hidden and its id taken until a later start completes it. The
* search purge alone is best effort: the same purge already ran when the context was removed.
*
* <p>Known limit: an update to an entry of the context that was loaded before the removal, and that commits
* after the job's last pass over the context's graphs, leaves that entry's graph behind.
*/
@Slf4j
final class ContextRemover {
/** Passes over the context's graphs, or its data folder, before giving up on what keeps appearing in them. */
private static final int MAX_PASSES = 3;
/** A live reindex skips a removed context; only the full wipe of a startup reindex reaches its documents. */
private static final String SEARCH_PURGE_HINT =
"only a reindex at startup (entrystore.solr.reindex-on-startup with .wait) removes any left";
private final RepositoryManagerImpl repositoryManager;
private final Repository repository;
private final IRI contextsIndexGraph;
private final ExactRemoval exactRemoval;
private final Set<String> pending = ConcurrentHashMap.newKeySet();
private final ExecutorService executor =
Executors.newSingleThreadExecutor(Thread.ofPlatform().name("context-removal").daemon().factory());
/** Set by {@link #shutdown()}. Package-private so a test can tell when the job will stop. */
volatile boolean stopping;
/** Statements removed per transaction. Package-private and non-final so tests can force several chunks. */
volatile int chunkSize = 10_000;
/** Graphs listed at a time, which bounds the heap a large context takes. Package-private for tests. */
volatile int graphsPerListing = 10_000;
/**
* Whether to remove a statement holding blank nodes by a pattern with wildcards in their place: a SPARQL store
* cannot match blank nodes it returned, while a pattern on a store without a context-first index can scan.
* Package-private for tests.
*/
volatile boolean blankNodesByPattern;
/** Supplies the search index to purge, or null without Solr. Package-private for tests. */
volatile Supplier<SearchIndex> searchIndex;
/** Run on the job thread before each chunk is read; for tests. */
volatile Runnable beforeChunk = () -> {};
/** Run on the job thread after each chunk has been committed and the monitor released; for tests. */
volatile Runnable afterChunk = () -> {};
/** Run on the job thread before each file or folder of a data folder is deleted; for tests. */
volatile Consumer<Path> beforeDelete = path -> {};
ContextRemover(RepositoryManagerImpl repositoryManager, IRI contextsIndexGraph) {
this(repositoryManager, repositoryManager.getRepository(), contextsIndexGraph);
}
/** Works on {@code repository} in place of the repository manager's; for tests. */
ContextRemover(RepositoryManagerImpl repositoryManager, Repository repository, IRI contextsIndexGraph) {
this.repositoryManager = repositoryManager;
this.repository = repository;
this.contextsIndexGraph = contextsIndexGraph;
this.exactRemoval = new ExactRemoval(repositoryManager);
this.searchIndex = repositoryManager::getIndex;
this.blankNodesByPattern = repository instanceof SPARQLRepository;
}
boolean isPending(String contextId) {
return contextId != null && pending.contains(contextId);
}
/**
* Takes the id of a context whose marker has just been committed out of use and starts deleting its graphs.
* Does not throw: the removal of the context already stands, and a job that cannot be started is resumed on
* the next start.
*/
void schedule(String contextId) {
pending.add(contextId);
submit(contextId);
}
/**
* Takes the ids of the contexts whose removal had not finished out of use and resumes deleting their graphs.
* A context already pending is skipped, so calling this again does not start a second job.
*/
void resumePending() {
List<String> contextIds = new ArrayList<>();
String base = repositoryManager.getRepositoryURL().toString();
try (RepositoryConnection rc = repository.getConnection();
RepositoryResult<Statement> markers = rc.getStatements(
null, RepositoryProperties.removalPending, null, false, contextsIndexGraph)) {
for (Statement marker : markers) {
String contextId = URISplit.getLastSegment(marker.getSubject().stringValue());
// the id names graphs and a folder to delete, so a marker that names no context is not acted on
if (contextId.isEmpty() || !marker.getSubject().stringValue().equals(base + contextId)) {
log.error("Removal marker {} names no context of this repository; ignoring it", marker);
continue;
}
contextIds.add(contextId);
}
}
for (String contextId : contextIds) {
if (pending.add(contextId)) {
log.info("Resuming the removal of context {}", contextId);
submit(contextId);
}
}
}
/** Stops the job between two chunks; the markers stay, so the next start resumes it. */
void shutdown() {
stopping = true;
executor.shutdown();
try {
if (!executor.awaitTermination(30, TimeUnit.SECONDS)) {
log.warn("Context removal did not stop within 30 seconds");
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
/** Waits until every job scheduled so far has ended; for tests. */
void awaitIdle() throws InterruptedException, ExecutionException, TimeoutException {
executor.submit(() -> {}).get(60, TimeUnit.SECONDS);
}
private void submit(String contextId) {
try {
executor.execute(() -> remove(contextId));
} catch (RejectedExecutionException e) {
log.error("Could not start removing context {}, the removal resumes on the next start", contextId, e);
}
}
private void remove(String contextId) {
Removal removal = new Removal(contextId);
long start = System.currentTimeMillis();
log.info("Removing context {}", contextId);
try {
removal.removeGraphs();
removeSearchDocuments(contextId, removal.contextURI);
deleteDataFolder(contextId);
// sweeps what an entry loaded before the removal has written meanwhile
removal.removeGraphs();
complete(contextId, removal.contextURI);
log.info("Removed context {} ({} statements) in {} ms", contextId, removal.removed,
System.currentTimeMillis() - start);
} catch (StoppedException e) {
log.info("Stopped removing context {} after {} statements, the removal resumes on the next start",
contextId, removal.removed);
} catch (Throwable e) {
log.error("Removing context {} failed after {} statements; it stays hidden and the removal resumes on "
+ "the next start", contextId, removal.removed, e);
// logged first: the executor would otherwise report it on System.err only
if (e instanceof Error error) {
throw error;
}
}
}
/** Up to {@link #graphsPerListing} graphs of the context: its index graph and the graphs under its URI. */
private List<IRI> listGraphs(String contextURI) {
int limit = graphsPerListing;
List<IRI> graphs = new ArrayList<>();
try (RepositoryConnection rc = repository.getConnection();
RepositoryResult<Resource> namedGraphs = rc.getContextIDs()) {
while (graphs.size() < limit && namedGraphs.hasNext()) {
if (namedGraphs.next() instanceof IRI graph && isOfContext(graph, contextURI)) {
graphs.add(graph);
}
}
}
return graphs;
}
private static boolean isOfContext(IRI iri, String contextURI) {
return iri.stringValue().equals(contextURI) || iri.stringValue().startsWith(contextURI + "/");
}
/** Best effort, see the class Javadoc: a failure is logged and the job goes on. */
private void removeSearchDocuments(String contextId, String contextURI) {
SearchIndex index = searchIndex.get();
if (index == null) {
return;
}
try {
if (!index.removeContext(URI.create(contextURI))) {
log.error("Could not remove the search documents of removed context {}; {}", contextId,
SEARCH_PURGE_HINT);
}
} catch (RuntimeException e) {
log.error("Could not remove the search documents of removed context {}; {}: {}", contextId,
SEARCH_PURGE_HINT, e.getMessage(), e);
}
}
/**
* Deletes the context's folder in the data folder. Refuses anything but a direct child of the data folder,
* such as a symbolic link or a folder an odd id resolves to, and does not follow links inside it. An upload in
* flight when the context was removed may still add or delete its staging files, so a file that vanishes is
* skipped and a folder that gained one is deleted again.
*/
private void deleteDataFolder(String contextId) throws IOException {
String configured = repositoryManager.getConfiguration().getString(Settings.DATA_FOLDER);
if (configured == null) {
return;
}
File root = DataImpl.dataFolder(configured).getCanonicalFile();
File folder = new File(root, contextId);
if (!folder.exists()) {
return;
}
if (!root.equals(folder.getCanonicalFile().getParentFile())) {
throw new IOException("Refusing to delete " + folder + ", which is not a folder in the data folder "
+ root);
}
for (int pass = 1; pass < MAX_PASSES; pass++) {
try {
deleteTree(folder.toPath());
return;
} catch (DirectoryNotEmptyException e) {
log.info("A file appeared in {} while it was being deleted, deleting it again", e.getFile());
}
}
deleteTree(folder.toPath());
}
/** Deletes a folder and what it holds without following links, skipping a file that vanishes meanwhile. */
private void deleteTree(Path folder) throws IOException {
Files.walkFileTree(folder, new SimpleFileVisitor<>() {
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attributes) throws IOException {
beforeDelete.accept(file);
Files.deleteIfExists(file);
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult visitFileFailed(Path file, IOException e) throws IOException {
if (e instanceof NoSuchFileException) {
return FileVisitResult.CONTINUE;
}
throw e;
}
@Override
public FileVisitResult postVisitDirectory(Path dir, IOException e) throws IOException {
if (e != null && !(e instanceof NoSuchFileException)) {
throw e;
}
beforeDelete.accept(dir);
Files.deleteIfExists(dir);
return FileVisitResult.CONTINUE;
}
});
}
/**
* Evicts the context's entries from the cache, which the pending id still hides, then removes the marker and
* frees the id. The evicted entries, and the context instances they hold, are flagged deleted first: a thread
* may still hold them after the id is freed.
*/
private void complete(String contextId, String contextURI) {
for (Entry entry : repositoryManager.getSoftCache().removeByEntryURIPrefix(contextURI + "/")) {
if (entry instanceof EntryImpl entryImpl) {
entryImpl.markDeleted();
}
if (entry.getContext() instanceof ContextImpl context) {
context.markDeleted();
}
}
synchronized (repository) {
try (RepositoryConnection rc = repository.getConnection()) {
rc.remove(iri(contextURI), RepositoryProperties.removalPending, null, contextsIndexGraph);
}
pending.remove(contextId);
}
}
/** Thrown between two chunks once {@link #shutdown()} has been called. */
private static final class StoppedException extends Exception {
}
/** One run of the job over one context, counting its passes and the statements it removed. */
private final class Removal {
private final String contextId;
private final String contextURI;
private int pass;
private long removed;
private Removal(String contextId) {
this.contextId = contextId;
// concatenated as URISplit.createURI does, but without its parsing, which could throw outside the try
this.contextURI = repositoryManager.getRepositoryURL().toString() + contextId;
}
/**
* Removes the context's graphs pass by pass, until a listing finds none. A listing cut off at
* {@link #graphsPerListing} continues the pass rather than starting a new one, unless it lists a graph the
* previous listing removed: graphs that survive their removal would otherwise fill every listing forever.
*/
private void removeGraphs() throws StoppedException {
Set<IRI> previous = Set.of();
for (List<IRI> graphs = listGraphs(contextURI); !graphs.isEmpty(); graphs = listGraphs(contextURI)) {
boolean newPass = graphs.size() < graphsPerListing || graphs.stream().anyMatch(previous::contains);
if (newPass && ++pass > MAX_PASSES) {
throw new IllegalStateException(graphs.size() + " graphs remain after " + MAX_PASSES + " passes");
}
removeGraphs(graphs);
previous = Set.copyOf(graphs);
}
}
/**
* Removes the statements of the graphs chunk by chunk. A graph larger than the room left in a chunk is
* read again after the chunk is committed, which then returns the statements not yet removed.
*/
private void removeGraphs(List<IRI> graphs) throws StoppedException {
List<Statement> chunk = new ArrayList<>();
// a set: sources of one triple in several graphs share its copy, which is then checked once
Set<Statement> copies = new LinkedHashSet<>();
try (RepositoryConnection reader = repository.getConnection()) {
startChunk();
for (IRI graph : graphs) {
String path = pathOf(graph);
boolean fromEntryGraph = path.equals(RepositoryProperties.ENTRY_PATH);
boolean relationSource = fromEntryGraph || path.equals(RepositoryProperties.MD_PATH)
|| path.equals(RepositoryProperties.EXTERNAL_MD_PATH);
List<Statement> removedOfGraph = List.of();
while (true) {
List<Statement> read = ExactRemoval.read(reader, graph, chunkSize - chunk.size());
if (!read.isEmpty() && removedOfGraph.contains(read.getFirst())) {
throw new IllegalStateException("Statements of graph " + graph + " were not removed");
}
chunk.addAll(read);
if (relationSource) {
copies.addAll(exactRemoval.relationCopies(reader, read, fromEntryGraph,
object -> isOfContext(object, contextURI)));
}
if (chunk.size() < chunkSize) {
break;
}
apply(chunk, copies);
removedOfGraph = read;
chunk.clear();
copies.clear();
startChunk();
}
}
}
if (!chunk.isEmpty()) {
apply(chunk, copies);
}
}
private void startChunk() throws StoppedException {
if (stopping) {
throw new StoppedException();
}
beforeChunk.run();
}
/** The path segment of one of the context's graphs, such as {@code metadata}, or empty for its index graph. */
private String pathOf(IRI graph) {
String rest = graph.stringValue().substring(contextURI.length());
int end = rest.indexOf('/', 1);
return rest.isEmpty() ? "" : rest.substring(1, end < 0 ? rest.length() : end);
}
/**
* Removes the chunk in one transaction under the monitor. Whether a copy is still stated outside the context
* is checked there, since a surviving entry may have stated the same triple after the chunk was read.
*/
private void apply(List<Statement> statements, Collection<Statement> copies) {
synchronized (repository) {
try (RepositoryConnection rc = repository.getConnection()) {
rc.begin();
try {
ExactRemoval.removeOwn(rc, statements, blankNodesByPattern, "context " + contextId);
exactRemoval.removeCopies(rc, copies, graph -> isOfContext(graph, contextURI));
rc.commit();
} catch (RuntimeException e) {
try {
rc.rollback();
} catch (RuntimeException rollbackFailure) {
e.addSuppressed(rollbackFailure);
}
throw e;
}
}
}
removed += statements.size();
log.info("Removing context {}: {} statements removed (pass {})", contextId, removed, pass);
afterChunk.run();
}
}
}