capacity-fixed

Rationale

Why. The number of keys is a bound a caller can state before knowing anything about the values.

Key Concepts

Counting keys

Role. Each Insert counts its key and each Evict releases it, so each cache needs its own instance. Holding exactly the limit is not exceeded.

Pattern. STRATEGY, OBSERVER

How It Works

Guarantees. No public parameter takes null and no public method returns it, declared with contrax's @PreCondition(IsNotNull.class) and @PostCondition(IsNotNull.class). A limit below one throws IllegalArgumentException. Keys are distinct by equals.

Thread safety. update and exceeded() may be called concurrently.

Lane

Purpose. Bounding a cache by how many keys it keeps.

Alternative. capacity-heap to bound a cache by the JVM's used heap.

When to avoid. Values whose sizes differ widely: a count of keys says nothing of the memory they hold.

Usage

A limit of two: a repeated key counts once, and a Hit changes nothing

import java.time.Instant;
import software.visionary.cache.capacity.Capacity;
import software.visionary.cache.capacity.fixed.FixedSize;
import software.visionary.cache.events.Evict;
import software.visionary.cache.events.Hit;
import software.visionary.cache.events.Insert;

Instant now = Instant.now();
Capacity<String> capacity = new FixedSize<>(2);

capacity.update(new Insert.Key<>("a", now));
capacity.update(new Insert.Key<>("a", now));
capacity.update(new Insert.Key<>("b", now));
System.out.println(capacity.exceeded());

capacity.update(new Insert.Key<>("c", now));
capacity.update(new Hit.Occurred<>("c", now));
System.out.println(capacity.exceeded());

capacity.update(new Evict.Occurred<>("a", now));
System.out.println(capacity.exceeded());

Output

false
true
false

Dependencies

• software.visionary:cache:2026.10.13 at Compile
• software.visionary.contrax:processor:2026.10.13 at Processor
• software.visionary:junit-closure:2026.09.17 at Testing

Views

Drawn from the release. A link in a view opens its source at the release tag.