SoftCache.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.Getter;
import lombok.extern.slf4j.Slf4j;
import org.entrystore.Entry;
import java.lang.ref.Reference;
import java.lang.ref.ReferenceQueue;
import java.lang.ref.SoftReference;
import java.net.URI;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
/**
* Soft-reference cache for Entry objects, mapping entry URIs to entries and maintaining a reverse
* index from resource/metadata/relation URIs back to entry URIs.
*
* <p>Concurrency model: each ConcurrentHashMap operation is individually atomic, but compound
* operations spanning both maps (cache + uri2entryURIs) are NOT atomic as a group. This is
* acceptable because callers handle cache misses gracefully (fall back to repository lookup),
* and same-entry put()/remove() never races in practice (they are distinct lifecycle events).
*
* <p>Copy-on-write in push()/pop(): the merge/computeIfPresent remapping functions create a new
* Set rather than mutating the existing one. This is required because (1) the ConcurrentHashMap
* contract states remapping functions should be side-effect-free as they may be re-applied under
* contention, and (2) getByURI() reads the Set outside any lock — mutating in place could expose
* a partially-updated Set to concurrent readers.
*/
@Slf4j
public class SoftCache {
private final ConcurrentHashMap<URI, SoftReference<Entry>> cache = new ConcurrentHashMap<>();
private final ConcurrentHashMap<URI, Object> uri2entryURIs = new ConcurrentHashMap<>();
private final Thread remover;
private final ReferenceQueue<Entry> clearedRefs;
@Getter
private volatile boolean shutdown = false;
public SoftCache() {
clearedRefs = new ReferenceQueue<>();
// start thread to delete cleared references from the cache
remover = new Remover(clearedRefs, this);
remover.start();
// add a shutdown hook to interrupt the endless loop
// the hook is only called when the whole VM is shutdown
Runtime.getRuntime().addShutdownHook(new Thread(this::shutdown));
}
int cacheSize() {
return cache.size();
}
public void clear() {
cache.clear();
uri2entryURIs.clear();
}
public void put(Entry entry) {
if (entry == null) return;
URI entryURI = entry.getEntryURI();
cache.put(entryURI, new EntrySoftReference(entry, clearedRefs));
push(entry.getLocalMetadataURI(), entryURI);
push(entry.getExternalMetadataURI(), entryURI);
push(entry.getResourceURI(), entryURI);
push(entry.getRelationURI(), entryURI);
}
@SuppressWarnings("unchecked")
private void push(URI from, URI to) {
if (from == null || to == null) {
return;
}
uri2entryURIs.merge(from, to, (existing, newVal) -> {
if (existing.equals(newVal)) {
return existing;
}
Set<URI> set = new HashSet<>();
if (existing instanceof Set) {
set.addAll((Set<URI>) existing);
} else {
set.add((URI) existing);
}
set.add((URI) newVal);
return set;
});
}
@SuppressWarnings("unchecked")
private void pop(URI from, URI to) {
if (from == null || to == null) {
return;
}
uri2entryURIs.computeIfPresent(from, (_, existing) -> {
if (existing instanceof Set) {
Set<URI> newSet = new HashSet<>((Set<URI>) existing);
newSet.remove(to);
return newSet.isEmpty() ? null : newSet;
}
return existing.equals(to) ? null : existing;
});
}
public void remove(Entry entry) {
if (entry == null) return;
URI entryURI = entry.getEntryURI();
cache.remove(entryURI);
pop(entry.getLocalMetadataURI(), entryURI);
pop(entry.getExternalMetadataURI(), entryURI);
pop(entry.getResourceURI(), entryURI);
pop(entry.getRelationURI(), entryURI);
}
/**
* Removes every cached entry whose entry URI starts with the prefix, such as all entries of one context.
*
* @return the removed entries the garbage collector had not cleared yet
*/
public List<Entry> removeByEntryURIPrefix(String prefix) {
List<Entry> removed = new ArrayList<>();
cache.forEach((entryURI, ref) -> {
if (entryURI.toString().startsWith(prefix) && ref instanceof EntrySoftReference esr
&& removeReference(esr) && esr.get() instanceof Entry entry) {
removed.add(entry);
}
});
return removed;
}
/** Removes a reference by the URIs it recorded when cached, unless it has been replaced since. */
private boolean removeReference(EntrySoftReference esr) {
if (!cache.remove(esr.entryURI, esr)) {
return false;
}
pop(esr.localMetadataURI, esr.entryURI);
pop(esr.externalMetadataURI, esr.entryURI);
pop(esr.resourceURI, esr.entryURI);
pop(esr.relationURI, esr.entryURI);
return true;
}
public Entry getByEntryURI(URI uri) {
if (uri == null) {
return null;
}
SoftReference<Entry> sr = cache.get(uri);
if (sr != null) {
return sr.get();
}
return null;
}
@SuppressWarnings("unchecked")
public Set<Entry> getByURI(URI uri) {
if (uri == null) {
return null;
}
Object entryUris = uri2entryURIs.get(uri);
if (entryUris != null) {
HashSet<Entry> entries = new HashSet<>();
if (entryUris instanceof Set) {
for (URI entryURI : ((Set<URI>) entryUris)) {
Entry entry = getByEntryURI(entryURI);
if (entry != null) {
entries.add(entry);
}
}
} else {
Entry entry = getByEntryURI((URI) entryUris);
if (entry != null) {
entries.add(entry);
}
}
return entries.isEmpty() ? null : entries;
}
return null;
}
public void shutdown() {
if (remover == null || (shutdown && remover.isInterrupted())) {
return;
}
log.info("Shutting down SoftCache");
shutdown = true;
remover.interrupt();
}
private static class EntrySoftReference extends SoftReference<Entry> {
final URI entryURI;
final URI localMetadataURI;
final URI externalMetadataURI;
final URI resourceURI;
final URI relationURI;
EntrySoftReference(Entry entry, ReferenceQueue<Entry> queue) {
super(entry, queue);
this.entryURI = entry.getEntryURI();
this.localMetadataURI = entry.getLocalMetadataURI();
this.externalMetadataURI = entry.getExternalMetadataURI();
this.resourceURI = entry.getResourceURI();
this.relationURI = entry.getRelationURI();
}
}
private class Remover extends Thread {
private final ReferenceQueue<Entry> refQ;
private final SoftCache softCache;
public Remover(ReferenceQueue<Entry> rq, SoftCache softCache) {
super();
this.refQ = rq;
this.softCache = softCache;
setDaemon(true);
}
public void run() {
try {
while (!shutdown) {
Reference<? extends Entry> ref = refQ.remove();
try {
if (ref instanceof EntrySoftReference esr) {
softCache.removeReference(esr);
} else {
log.warn("Unexpected reference type dequeued from SoftCache: {}", ref.getClass().getName());
}
} catch (RuntimeException e) {
URI failedURI = (ref instanceof EntrySoftReference esr2) ? esr2.entryURI : null;
log.error("Error cleaning up soft reference for entry [{}], continuing", failedURI, e);
}
}
} catch (InterruptedException e) {
log.info("SoftCache remover got interrupted, shutting down");
}
}
}
}