HBASE-30020 Introduce cache placement and admission policy API

[VladRodionov]

This PR targets the HBASE-30018 feature branch.

Introduces the cache placement/admission policy layer for the pluggable block cache architecture.

Adds:

• CachePlacementAdmissionPolicy
• AdmissionDecision
• AdmissionPriority
• TierDecision
• PromotionDecision
• RepresentationDecision
• CacheRequestContext
• CacheWriteContext
• CacheWriteSource
• DefaultHBaseCachePlacementAdmissionPolicy

The default policy preserves current HBase behavior:

• admission is allowed by default after existing CacheConfig decisions
• metadata/index/bloom blocks prefer L1, with fallback to L2
• data blocks prefer L2, with fallback to L1
• representation preserves current HBase behavior
• no promotion by default

No read/write path migration is included in this PR.
No behavior change intended.

JIRA: HBASE-30020

[petersomogyi]

LGTM. Clean API design with good Javadocs.

[taklwu]

just two questions , but LGTM

[taklwu]

question: how would this repeat be used ? is it something we will define in the each implementation that more than X times lookup would considered as repeat?

[VladRodionov]

repeat preserves an existing HBase cache lookup semantic and is not intended as a hotness/frequency signal. Today HBase uses it mainly to avoid double-counting cache misses during retry or double-check-locking lookup paths.

[taklwu]

nit: will we have a demotion action ? IIRC that we may have block moving from L1 -> L2, ,if so and if need to record it, where should we action be annotated ?

[VladRodionov]

I think demotion is a separate topology operation and should not be encoded in PromotionAction.
PromotionAction is intentionally scoped to cache-hit handling: after a hit in one tier, the policy may decide whether to promote the block to a higher-priority tier. Demotion, if needed later, would likely be modeled separately, for example as DemotionDecision / DemotionAction, or recorded in topology-level metrics when CacheTopology#demote(...) is invoked. I would avoid mixing promotion and demotion into the same enum because they are triggered by different events: promotion is hit-driven, while demotion is usually eviction/pressure-driven. Besides this, demotion is quite expensive (you will need to expose CacheEngine internal eviction pipeline to listen to these events, not all cache implementations can be efficient)

For this PR, I’d keep PromotionAction limited to NONE and PROMOTE, and add demotion-specific decision/metrics later when we wire actual eviction callbacks or topology movement.

Btw, promotion is hard as well, you have to make sure that object being promoted is really worth it, otherwise you introduce additional layer of cache data trashing.

[wchevreuil]

LGTM.

[VladRodionov]

Thank you, @taklwu @wchevreuil and @petersomogyi.