HBASE-30329 Add topology-backed cache diagnostics and migrate single tier cache

[VladRodionov]

Summary

This PR extends the topology-backed cache access framework so that cache diagnostics and cache
access are consistently routed through TopologyBackedCacheAccessService.

The main change is that plain single-tier BlockCache implementations now use the same
topology-backed access path as combined caches. Single-tier caches are represented by
SingleTierTopology, while existing two-tier cache variants continue to use topology-specific
representations:

• BlockCache -> SingleTierTopology
• CombinedBlockCache -> TieredExclusiveTopology
• InclusiveCombinedBlockCache -> TieredInclusiveTopology

This keeps the legacy cache implementations underneath through BlockCacheBackedCacheEngine, but
moves the access-service boundary to the topology/cache-engine model.

Motivation

After HBASE-30305, exclusive combined-cache orchestration was moved behind
TopologyBackedCacheAccessService. Follow-up testing showed that diagnostic and compatibility paths
still had assumptions about BlockCacheBackedCacheAccessService and concrete BlockCache
implementations.

This PR removes those assumptions from the main factory path by making topology-backed access the
normal path for both single-tier and combined caches.

Changes

• Added SingleTierTopology.
• Added CacheTopologyType.SINGLE_TIER.
• Added topology-backed factory support for single-tier BlockCache instances.
• Added explicit topology-backed support for InclusiveCombinedBlockCache.
• Preserved separate semantics for exclusive and inclusive combined caches:
  • exclusive promotion moves a block between tiers;
  • inclusive promotion copies a block and keeps the source tier;
  • inclusive eviction evicts from all tiers.
• Added cached-block iterable diagnostics through the topology-backed service.
• Preserved legacy default cacheBlock(key, block) behavior for single-tier caches.
• Added test helpers for unwrapping legacy BlockCache instances from topology-backed services
  where tests still need direct compatibility checks.
• Added focused tests for:
  • single-tier topology-backed cache access;
  • exclusive combined-cache compatibility;
  • inclusive combined-cache compatibility.

Compatibility notes

BlockCacheBackedCacheAccessService is no longer the default factory result for plain block caches.
Instead, the main factory now returns a TopologyBackedCacheAccessService backed by
SingleTierTopology.

The underlying legacy BlockCache implementations are still preserved through
BlockCacheBackedCacheEngine. This PR does not migrate LruBlockCache, BucketCache, or other
concrete cache implementations to native CacheEngine implementations yet. That remains a follow-up
migration step.

Testing

Focused tests:

mvn -pl hbase-server \
  -Dtest=TestSingleTierTopologyBackedCacheAccessService test

mvn -pl hbase-server \
  -Dtest=TestCombinedBlockCacheCompatibleTopologyBackedCacheAccessService test

mvn -pl hbase-server \
  -Dtest=TestInclusiveCombinedBlockCacheCompatibleTopologyBackedCacheAccessService test

mvn -pl hbase-server \
  -Dtest=TestHFile test

mvn -pl hbase-server \
  -Dtest=TestBlockCacheReporting test

[Copilot]

Pull request overview

Routes legacy block caches and diagnostics through the topology-backed cache framework.

Changes:

• Adds single-tier and inclusive topology-backed cache support.
• Adds aggregated cached-block iteration diagnostics.
• Migrates compatibility helpers and tests to topology-backed services.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
TestCacheOnWrite.java	Uses topology-aware cache unwrapping.
TestCacheConfig.java	Verifies topology-backed configuration.
TestSingleTierTopologyBackedCacheAccessService.java	Tests single-tier behavior.
TestInclusiveCombinedBlockCacheCompatibleTopologyBackedCacheAccessService.java	Tests inclusive topology semantics.
TestCacheAccessServices.java	Updates factory expectations.
TestBlockCacheBackedCacheAccessService.java	Removes legacy adapter tests.
CacheAccessServiceTestFactory.java	Unwraps topology-backed caches.
CacheConfig.java	Preserves single-tier legacy cache access.
TopologyBackedCacheAccessServices.java	Adds single-tier and inclusive factories.
TopologyBackedCacheAccessService.java	Adds single-tier writes and block iteration.
SingleTierTopology.java	Defines the single-tier topology.
SingleEngineTopology.java	Renames its topology type.
DefaultHBaseCachePlacementAdmissionPolicy.java	Updates single-tier policy handling.
CacheTopologyType.java	Introduces SINGLE_TIER.
CacheAccessServices.java	Routes all cache variants by topology.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[taklwu]

actually we get more than just topology-backed cache diagnostics , the single-tier caches refactoring. maybe call the title as Add topology-backed cache diagnostics and migrate single tier cache

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/NonVictimDelegatingFirstLevelCacheEngine.java:110

• The block-type-aware overload has the same non-atomic containsBlock/getBlock sequence. A concurrent eviction can make the second call delegate to the victim cache, and the early-return miss path also omits L1 miss metrics. Route this overload through the same atomic local-only lookup mechanism as the other overload.

    if (!firstLevelBlockCache.containsBlock(cacheKey)) {
      return null;
    }

    return super.getBlock(cacheKey, caching, repeat, updateCacheMetrics, blockType);