Imported from Jahia/formidable (.agents/skills/jahia-java-concurrency/SKILL.md). Install upstream with npx skills add Jahia/formidable --skill jahia-java-concurrency. Copyright stays with the author.

Concurrency and Thread Safety for Jahia Java Backend

In a Jahia webapp, every OSGi service is a singleton — its instance fields are shared across every concurrent request, publication job, event listener, and background thread. A field that looks fine in a single-threaded test can silently corrupt data or read stale values under real load.

This skill covers the correct patterns and the pitfalls. Both developers and reviewers use it.

OSGi-specific concurrency (@Modified config reload, @Reference dynamic rebinding) is covered in /jahia-java-osgi. This skill covers the general Java concurrency model applicable to all backend code.

The three questions to ask about any mutable field

Before writing or reviewing any instance or static field in a service:

1. Can it be written by more than one thread? If yes → needs synchronization or an atomic type.
2. Can it be read while another thread is writing it? If yes → at minimum needs volatile.
3. Are read + write part of a compound action (check-then-act, read-modify-write)? If yes → volatile alone is not enough, needs a lock or an atomic with CAS.

Immutability — the first line of defence

Correct approach

Prefer immutable objects. An immutable object needs no synchronization — it is inherently thread-safe.

• Make fields final wherever possible.
• Use record types for config/value objects (all fields are final by definition).
• Use List.of(), Map.of(), Set.of() for collections that do not change after construction.
• Return copies or unmodifiable views of mutable internal collections rather than the live reference.

Pitfall

// dangerous — caller can mutate the internal list
public List<String> getAllowedRoles() {
    return allowedRoles; // returns live mutable reference
}

Return Collections.unmodifiableList(allowedRoles) or List.copyOf(allowedRoles) instead.

volatile — correct use and limits

Correct use

volatile guarantees visibility: a write to a volatile field is immediately visible to all subsequent reads in other threads. Use it when:

• One thread writes, many threads read (no compound action needed).
• The written value is a single reference or primitive (not two fields that must be updated atomically together).

// correct — single writer (SCR @Modified), many readers
private volatile Config config;

@Activate @Modified
void activate(Cfg cfg) {
    this.config = new Config(cfg); // atomic reference swap
}

Limits — volatile is NOT enough for compound actions

// WRONG — read-modify-write is not atomic even with volatile
private volatile int counter = 0;
public void increment() {
    counter++; // read, increment, write — three steps, not one
}

Two threads can both read counter = 5, both compute 6, and both write 6 — losing one increment. Use AtomicInteger.incrementAndGet() instead.

Similarly, volatile does not protect two fields that must be consistent with each other:

// WRONG — reader can see updated 'host' with old 'port'
private volatile String host;
private volatile int port;

Bundle related fields into a single immutable record and swap the reference atomically (as shown in /jahia-java-osgi).

Atomic variables

Use java.util.concurrent.atomic for lock-free, thread-safe single-value updates:

Check-then-act with compareAndSet

// correct — atomic conditional update
AtomicReference<State> stateRef = new AtomicReference<>(State.IDLE);

public boolean tryStart() {
    return stateRef.compareAndSet(State.IDLE, State.RUNNING);
}

Two threads calling tryStart() concurrently: only one gets true. No lock needed.

Synchronized blocks and ReentrantLock

When to use

Use explicit locking when:

• The critical section spans multiple statements that must execute atomically.
• You need read/write distinction (ReadWriteLock).
• You need a timed or interruptible lock attempt (ReentrantLock.tryLock(timeout)).

Correct approach

// small, focused critical section
private final Object lock = new Object();
private List<String> items = new ArrayList<>();

public void addItem(String item) {
    synchronized (lock) {
        items.add(item);
    }
}

public List<String> snapshot() {
    synchronized (lock) {
        return List.copyOf(items); // return a copy, not the live list
    }
}

Pitfalls

• Locking on this. Callers can also synchronized(service) from outside, causing unexpected contention or deadlock. Prefer a private final Object lock.
• Holding a lock during I/O or JCR calls. A lock held while doing a JCR query or an HTTP call blocks all other threads waiting for it. Move I/O outside the critical section; only protect the state mutation.
• Inconsistent lock object. Two methods protecting the same state must use the same lock.
• Deadlock. Two threads each holding lock A and waiting for lock B. Always acquire multiple locks in the same fixed order. Prefer tryLock(timeout) and fail gracefully rather than block indefinitely.

ReadWriteLock for read-heavy state

private final ReadWriteLock rwLock = new ReentrantReadWriteLock();
private Map<String, String> cache = new HashMap<>();

public String get(String key) {
    rwLock.readLock().lock();
    try { return cache.get(key); }
    finally { rwLock.readLock().unlock(); }
}

public void put(String key, String value) {
    rwLock.writeLock().lock();
    try { cache.put(key, value); }
    finally { rwLock.writeLock().unlock(); }
}

Multiple readers proceed concurrently; a writer gets exclusive access. Worth the complexity only when reads heavily outnumber writes.

Thread-safe collections

Pitfall — compound actions on ConcurrentHashMap

// WRONG — check-then-put is not atomic
if (!map.containsKey(key)) {
    map.put(key, value);
}
// CORRECT
map.putIfAbsent(key, value);
// or for a more complex compute:
map.computeIfAbsent(key, k -> expensiveCreate(k));

Even ConcurrentHashMap does not make compound actions atomic unless you use the atomic methods (putIfAbsent, computeIfAbsent, merge, compute).

Static fields

Pitfall

Static fields are shared across all class loader instances — effectively global state in a webapp. A static mutable field is the most dangerous form of shared state: it is not scoped to a component lifecycle, so it outlives bundle reactivations and can carry stale state.

// dangerous — static mutable state in a webapp
private static Map<String, Object> cache = new HashMap<>();

Rule: static fields in a Jahia module must be either:

• final and truly immutable (constants, loggers), or
• volatile / concurrent-typed with documented thread-safety, or
• ThreadLocal (thread-scoped, not shared).

If you need a cache or shared service state, use an OSGi @Component instance field — the OSGi lifecycle manages it correctly.

ThreadLocal

ThreadLocal gives each thread its own isolated copy of a variable. Correct for per-request state (locale, user context, transaction context).

Pitfall — thread pool reuse

Jahia uses thread pools. A ThreadLocal set during request A and not cleared will be visible during a later request B handled by the same thread:

// always clean up in a finally block
threadLocal.set(value);
try {
    doWork();
} finally {
    threadLocal.remove(); // mandatory
}

Failing to call remove() is a P1 finding — stale user context or locale leaked to subsequent requests.

JCR sessions are NOT thread-safe

A JCRSessionWrapper must never be shared across threads. Do not store a session as an instance field of an OSGi service and reuse it across requests.

// WRONG — shared session across threads
@Component
public class MyService {
    private JCRSessionWrapper session; // one session, all threads — crash under concurrency
}

Always obtain a fresh session per-thread (and per-locale where i18n matters) and close it in a finally block or via JCRTemplate.

Lazy initialization

Correct approach — volatile + double-checked locking

private volatile ExpensiveObject instance;

public ExpensiveObject get() {
    if (instance == null) {                    // first check (no lock)
        synchronized (this) {
            if (instance == null) {            // second check (with lock)
                instance = new ExpensiveObject();
            }
        }
    }
    return instance;
}

Without volatile, the JVM may publish a partially-constructed object due to instruction reordering. volatile on the field is mandatory for double-checked locking to be correct.

Simpler alternative — holder idiom

// no synchronization needed — class loading is inherently thread-safe
private static class Holder {
    static final ExpensiveObject INSTANCE = new ExpensiveObject();
}
public static ExpensiveObject get() { return Holder.INSTANCE; }

Review checklist

When reviewing any class in a Jahia module, check:

1. Instance fields of @Component services — are mutable ones volatile, atomic, or synchronized?
2. Static mutable fields — flag immediately; require justification and correct synchronization.
3. Compound actions — every check-then-act or read-modify-write on a shared field needs a lock or atomic CAS.
4. Collections returned from getters — are they copies or unmodifiable views?
5. JCR sessions — never stored as instance fields; always obtained and closed per-thread.
6. ThreadLocal — always cleaned up in a finally block.
7. Locks — held for the minimum possible time; no I/O inside a critical section.
8. Undocumented thread-safety contract — if the class is not internally thread-safe, its Javadoc must say so and name the required external synchronization.