codeflash-agent/plugin/languages/java/references/library-replacement.md

Library Boundary Breaking -- Java

Domain agents treat external libraries as walls they can't cross. The deep agent doesn't. When profiling shows an external library dominating runtime and domain agents have plateaued, the deep agent has authority to replace library calls with focused JDK stdlib implementations that only cover the subset the codebase actually uses.

When to consider this

All three conditions must hold:

1. Profiling evidence: The library accounts for >15% of cumtime (JFR CPU sampling), AND the cost is in the library's internal machinery (reflection, tree building, generalized parsing), not in your code's usage of it
2. Plateau evidence: A domain agent already tried to optimize around the library -- caching results, reducing call frequency, batching -- and still plateaued because the remaining calls are essential but the library's implementation is heavy
3. Narrow usage surface: The codebase uses a small fraction of the library's API. If you're using 5 methods out of 200, a focused replacement is feasible. If you're using most of the API, it's not worth it

How to assess feasibility

Step 1 -- Audit the actual API surface

# What does the codebase actually import?
grep -rn "import com.google.common" --include="*.java" --include="*.kt" src/ | sort -u
grep -rn "import org.apache.commons" --include="*.java" --include="*.kt" src/ | sort -u

# What classes/methods are actually called?
grep -rn "Preconditions\.\|ImmutableList\.\|ImmutableMap\.\|Strings\." --include="*.java" src/ | sort -u

Step 2 -- Classify each usage

For each call site, determine:

• What does it need? (null check, immutable collection, string manipulation, date conversion)
• What subset of the library's type system does it touch?
• Could JDK stdlib handle this use case? (check minimum JDK version from setup.md)
• Does it depend on library-specific features (e.g., Guava's @VisibleForTesting, custom serialization)?

Step 3 -- Map the replacement boundary

• Replace: Uses where JDK stdlib provides equivalent functionality (collection factories, string checks, null guards)
• Keep: Uses where the library provides functionality JDK lacks (e.g., Guava's Cache with TTL, Commons CSV parsing)
• Hybrid: Replace read-only/simple uses, keep complex uses

Step 4 -- Estimate effort vs payoff

A focused replacement is worth it when:

• The library calls being replaced account for >20% of total runtime
• The replacement uses JDK stdlib only -- no new dependencies
• The API surface being replaced is <10 methods/classes
• Correctness can be verified: run both library path and replacement, diff results

Common Java replacement patterns

Guava -> JDK stdlib

Guava API	JDK Replacement	Min JDK
ImmutableList.of(a, b, c)	List.of(a, b, c)	9
ImmutableList.copyOf(col)	List.copyOf(col)	10
ImmutableMap.of(k, v)	Map.of(k, v)	9
ImmutableSet.of(a, b)	Set.of(a, b)	9
Preconditions.checkNotNull(x, msg)	Objects.requireNonNull(x, msg)	7
Preconditions.checkArgument(cond, msg)	if (!cond) throw new IllegalArgumentException(msg)	1
Strings.isNullOrEmpty(s)	s == null || s.isEmpty()	1
Strings.nullToEmpty(s)	s == null ? "" : s	1
Joiner.on(",").join(items)	String.join(",", items)	8
Splitter.on(",").split(s)	s.split(",") (note: different empty-string behavior)	1
FluentIterable.from(col).transform(f)	col.stream().map(f).collect(toList())	8
Optional (Guava)	Optional (JDK)	8
Iterables.getOnlyElement(col)	manual: check size == 1, get(0)	1

Caution: List.of() / Map.of() return truly immutable collections that throw on null elements. Guava's ImmutableList also rejects nulls, so this is safe. But if code passes these to APIs expecting mutable lists, it will break.

Apache Commons Lang -> JDK stdlib

Commons API	JDK Replacement	Min JDK
StringUtils.isBlank(s)	s == null || s.isBlank()	11
StringUtils.isEmpty(s)	s == null || s.isEmpty()	1
StringUtils.strip(s)	s.strip()	11
StringUtils.trimToNull(s)	s == null ? null : (s.isBlank() ? null : s.strip())	11
StringUtils.join(arr, sep)	String.join(sep, arr)	8
StringUtils.defaultIfBlank(s, def)	s == null || s.isBlank() ? def : s	11
ObjectUtils.defaultIfNull(obj, def)	Objects.requireNonNullElse(obj, def)	9
ObjectUtils.firstNonNull(a, b, c)	Stream.of(a, b, c).filter(Objects::nonNull).findFirst().orElse(null)	8

Apache Commons Collections -> JDK

Commons API	JDK Replacement	Min JDK
CollectionUtils.isEmpty(col)	col == null || col.isEmpty()	1
CollectionUtils.isNotEmpty(col)	col != null && !col.isEmpty()	1
IterableUtils.forEach(iter, closure)	iter.forEach(closure)	8
MapUtils.getInteger(map, key, def)	(Integer) map.getOrDefault(key, def)	8
CollectionUtils.select(col, pred)	col.stream().filter(pred).collect(toList())	8

Jackson/Gson: full tree vs streaming

When profiling shows Jackson ObjectMapper.readTree() or readValue() dominating:

• If you only need 2-3 fields from a large JSON: use JsonParser (streaming API) to extract them without building the full tree
• If you deserialize the same type repeatedly: cache the ObjectReader (objectMapper.readerFor(MyClass.class)) -- ObjectMapper.readValue() creates a new one each time
• If serialization is the bottleneck: use JsonGenerator for targeted output instead of objectMapper.writeValueAsString()

Joda-Time -> java.time

Joda-Time	java.time	Min JDK
DateTime	ZonedDateTime	8
LocalDate (Joda)	LocalDate (JDK)	8
LocalTime (Joda)	LocalTime (JDK)	8
Duration (Joda)	Duration (JDK)	8
Period (Joda)	Period (JDK)	8
DateTimeFormat.forPattern(p)	DateTimeFormatter.ofPattern(p)	8

Verification requirements

Library replacements are high-reward but high-risk. Always verify:

1. Diff test: Run both the library path and your replacement with representative inputs. Outputs must match exactly
2. Edge cases: null inputs, empty collections, empty strings, concurrent access, very large inputs
3. JDK version: Verify the project's minimum JDK version (from setup.md) supports the replacement API. List.of() needs JDK 9+, String.isBlank() needs JDK 11+
4. Serialization: If replaced types are serialized (Jackson, Java serialization, protobuf), verify wire compatibility. List.of() returns a non-serializable-compatible type in some JDK versions
5. Behavioral differences: Some replacements have subtle differences:
   • String.split(",") keeps trailing empty strings; Splitter.on(",") does not by default
   • List.of() throws on null elements; Arrays.asList() allows them
   • Map.of() is limited to 10 entries; use Map.ofEntries() for more