taklwu commented on code in PR #8231: URL: https://github.com/apache/hbase/pull/8231#discussion_r3235991376
########## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/NoOpCacheAccessService.java: ########## @@ -0,0 +1,216 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import java.util.Objects; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Disabled-cache implementation of {@link CacheAccessService}. + * <p> + * {@code NoOpCacheAccessService} is useful when block cache access is disabled but callers still + * want to depend on a non-null {@link CacheAccessService}. It never stores blocks, never returns + * cached blocks, reports zero capacity and occupancy, and treats all invalidation requests as + * no-ops. + * </p> + * <p> + * This implementation should not be used to hide configuration mistakes. It represents an explicit + * disabled-cache state and should be selected only when the caller has determined that no block + * cache is available or desired. + * </p> + */ [email protected] +public final class NoOpCacheAccessService implements CacheAccessService { Review Comment: nit: is this class used for testing purpose? ########## hbase-server/src/test/java/org/apache/hadoop/hbase/io/hfile/cache/TestBlockCacheBackedCacheAccessService.java: ########## @@ -0,0 +1,210 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +import java.util.Optional; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCache; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.BlockType; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.hadoop.hbase.io.hfile.HFileBlock; +import org.apache.hadoop.hbase.testclassification.IOTests; +import org.apache.hadoop.hbase.testclassification.SmallTests; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; + +/** + * Tests for {@link BlockCacheBackedCacheAccessService} and related service helpers. + */ +@Tag(IOTests.TAG) +@Tag(SmallTests.TAG) +public class TestBlockCacheBackedCacheAccessService { + + /** + * Verifies that context-based lookup delegates to the block-type aware legacy lookup method. + */ + @Test + void testGetBlockWithBlockTypeDelegatesToBlockCache() { + BlockCache blockCache = mock(BlockCache.class); + CacheAccessService service = new BlockCacheBackedCacheAccessService(blockCache); + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + + when(blockCache.getBlock(key, true, true, false, BlockType.DATA)).thenReturn(block); + + CacheRequestContext context = CacheRequestContext.newBuilder().setCaching(true).setRepeat(true) + .setUpdateCacheMetrics(false).setBlockType(BlockType.DATA).build(); + + assertSame(block, service.getBlock(key, context)); + verify(blockCache).getBlock(key, true, true, false, BlockType.DATA); + } + + /** + * Verifies that context-based lookup delegates to the legacy lookup method without block type. + */ + @Test + void testGetBlockWithoutBlockTypeDelegatesToBlockCache() { + BlockCache blockCache = mock(BlockCache.class); + CacheAccessService service = new BlockCacheBackedCacheAccessService(blockCache); + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + + when(blockCache.getBlock(key, true, false, true)).thenReturn(block); + + CacheRequestContext context = CacheRequestContext.newBuilder().setCaching(true).setRepeat(false) + .setUpdateCacheMetrics(true).build(); + + assertSame(block, service.getBlock(key, context)); + verify(blockCache).getBlock(key, true, false, true); + } + + /** + * Verifies that context-based insertion delegates in-memory and wait flags correctly. + */ + @Test + void testCacheBlockDelegatesToBlockCache() { + BlockCache blockCache = mock(BlockCache.class); + CacheAccessService service = new BlockCacheBackedCacheAccessService(blockCache); + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + + CacheWriteContext context = CacheWriteContext.newBuilder().setInMemory(true) + .setWaitWhenCache(true).setSource(CacheWriteSource.READ_MISS).build(); + + service.cacheBlock(key, block, context); + + verify(blockCache).cacheBlock(key, block, true, true); + } + + /** + * Verifies that invalidation methods delegate to the wrapped block cache. + */ + @Test + void testEvictionDelegatesToBlockCache() { + BlockCache blockCache = mock(BlockCache.class); + CacheAccessService service = new BlockCacheBackedCacheAccessService(blockCache); + BlockCacheKey key = new BlockCacheKey("file", 1L); Review Comment: nit: make `file` and `1L` into parameters and avoid typos in the future ? or even move `file` to class level, since may test are using the same filename ```suggestion String fileName = "file"; long offset = 1L; BlockCacheKey key = new BlockCacheKey(fileName, offset); ``` ########## hbase-server/src/test/java/org/apache/hadoop/hbase/io/hfile/cache/TestTopologyBackedCacheAccessService.java: ########## @@ -0,0 +1,414 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +import java.util.List; +import java.util.Optional; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.BlockType; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.hadoop.hbase.io.hfile.HFileBlock; +import org.apache.hadoop.hbase.testclassification.IOTests; +import org.apache.hadoop.hbase.testclassification.SmallTests; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; + +/** + * Tests for {@link TopologyBackedCacheAccessService}. + */ +@Tag(IOTests.TAG) +@Tag(SmallTests.TAG) +public class TestTopologyBackedCacheAccessService { + + /** + * Verifies that lookup checks topology tiers in order and returns the first cached block found. + */ + @Test + void testGetBlockChecksTiersInOrder() { + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + CacheTopology topology = mock(CacheTopology.class); + CacheTopologyView topologyView = mock(CacheTopologyView.class); + CachePlacementAdmissionPolicy policy = mock(CachePlacementAdmissionPolicy.class); + CacheEngine l1 = mock(CacheEngine.class); + CacheEngine l2 = mock(CacheEngine.class); + CacheRequestContext context = requestContext(); + + when(topology.getName()).thenReturn("tiered"); + when(topology.getView()).thenReturn(topologyView); + when(topology.getTiers()).thenReturn(List.of(CacheTier.L1, CacheTier.L2)); + when(topology.getEngine(CacheTier.L1)).thenReturn(Optional.of(l1)); + when(topology.getEngine(CacheTier.L2)).thenReturn(Optional.of(l2)); + when(l1.getBlock(key, true, false, true, BlockType.DATA)).thenReturn(null); + when(l2.getBlock(key, true, false, true, BlockType.DATA)).thenReturn(block); + when(policy.shouldPromote(key, block, CacheTier.L2, context, topologyView)) + .thenReturn(PromotionDecision.none()); + + CacheAccessService service = new TopologyBackedCacheAccessService(topology, policy); + + assertSame(block, service.getBlock(key, context)); + + verify(l1).getBlock(key, true, false, true, BlockType.DATA); + verify(l2).getBlock(key, true, false, true, BlockType.DATA); + verify(policy).shouldPromote(key, block, CacheTier.L2, context, topologyView); + } + + /** + * Verifies that a hit can trigger topology-level promotion when requested by policy. + */ + @Test + void testGetBlockPromotesOnPolicyDecision() { + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + CacheTopology topology = mock(CacheTopology.class); + CacheTopologyView topologyView = mock(CacheTopologyView.class); + CachePlacementAdmissionPolicy policy = mock(CachePlacementAdmissionPolicy.class); + CacheEngine l1 = mock(CacheEngine.class); + CacheEngine l2 = mock(CacheEngine.class); + CacheRequestContext context = requestContext(); + + when(topology.getView()).thenReturn(topologyView); + when(topology.getTiers()).thenReturn(List.of(CacheTier.L1, CacheTier.L2)); + when(topology.getEngine(CacheTier.L1)).thenReturn(Optional.of(l1)); + when(topology.getEngine(CacheTier.L2)).thenReturn(Optional.of(l2)); + when(l1.getBlock(key, true, false, true, BlockType.DATA)).thenReturn(null); + when(l2.getBlock(key, true, false, true, BlockType.DATA)).thenReturn(block); + when(policy.shouldPromote(key, block, CacheTier.L2, context, topologyView)) + .thenReturn(PromotionDecision.promoteTo(CacheTier.L1, false)); + when(topology.promote(key, block, l2, l1)).thenReturn(true); + + CacheAccessService service = new TopologyBackedCacheAccessService(topology, policy); + + assertSame(block, service.getBlock(key, context)); + + verify(policy).shouldPromote(key, block, CacheTier.L2, context, topologyView); + verify(topology).promote(key, block, l2, l1); + } + + /** + * Verifies that cache insertion is skipped when admission policy rejects the block. + */ + @Test + void testCacheBlockSkipsInsertionWhenRejected() { + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + CacheTopology topology = mock(CacheTopology.class); + CacheTopologyView topologyView = mock(CacheTopologyView.class); + CachePlacementAdmissionPolicy policy = mock(CachePlacementAdmissionPolicy.class); + CacheEngine engine = mock(CacheEngine.class); + CacheWriteContext context = writeContext(); + + when(topology.getView()).thenReturn(topologyView); + when(topology.getEngine(CacheTier.SINGLE)).thenReturn(Optional.of(engine)); + when(policy.shouldAdmit(key, block, context, AdmissionPriority.NORMAL, topologyView)) + .thenReturn(AdmissionDecision.reject("rejected")); + + CacheAccessService service = new TopologyBackedCacheAccessService(topology, policy); + + service.cacheBlock(key, block, context); + + verify(policy).shouldAdmit(key, block, context, AdmissionPriority.NORMAL, topologyView); + verify(policy, never()).selectTier(key, block, context, topologyView); + verify(engine, never()).cacheBlock(key, block, true, true); + } + + /** + * Verifies that admitted blocks are inserted into policy-selected tiers. + */ + @Test + void testCacheBlockInsertsIntoSelectedTier() { + BlockCacheKey key = new BlockCacheKey("file", 1L); + Cacheable block = mock(Cacheable.class); + CacheTopology topology = mock(CacheTopology.class); + CacheTopologyView topologyView = mock(CacheTopologyView.class); + CachePlacementAdmissionPolicy policy = mock(CachePlacementAdmissionPolicy.class); + CacheEngine engine = mock(CacheEngine.class); + CacheWriteContext context = writeContext(); + + when(topology.getView()).thenReturn(topologyView); + when(topology.getEngine(CacheTier.SINGLE)).thenReturn(Optional.of(engine)); + when(policy.shouldAdmit(key, block, context, AdmissionPriority.NORMAL, topologyView)) + .thenReturn(AdmissionDecision.admit()); + when(policy.selectRepresentation(key, block, context, topologyView)) + .thenReturn(RepresentationDecision.CURRENT_HBASE_DEFAULT); Review Comment: nit: I assumed this is just a mock call and the representation isn't used at the moment, will we have another alternative `TopologyBackedCacheAccessService` for other implementation? also, can you briefly explain how `TopologyBackedCacheAccessService` or `BlockCacheBackedCacheAccessService` could be configured in future ? ########## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/BlockCacheBackedCacheAccessService.java: ########## @@ -0,0 +1,298 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import java.util.Objects; +import java.util.Optional; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCache; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.BlockType; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.hadoop.hbase.io.hfile.HFileBlock; +import org.apache.yetus.audience.InterfaceAudience; + +/** + * {@link CacheAccessService} implementation backed by an existing {@link BlockCache} instance. + * <p> + * This adapter is the compatibility bridge for the first migration step. It allows new callers to + * depend on {@link CacheAccessService} while the runtime implementation still uses the current + * {@link BlockCache} hierarchy, including LruBlockCache, BucketCache, CombinedBlockCache, and other + * existing implementations. + * </p> + * <p> + * The adapter should not introduce new policy, placement, admission, representation, promotion, or + * topology behavior. Its purpose is to translate the new context-based service API into the current + * {@code BlockCache} API with no intentional behavior change. + * </p> + * <p> + * A future topology-backed service can replace this adapter after call sites have migrated to + * {@link CacheAccessService}. That future implementation may use {@link CacheTopology}, + * {@link CachePlacementAdmissionPolicy}, and {@link CacheEngine}; this adapter deliberately does + * not. + * </p> + */ [email protected] +public class BlockCacheBackedCacheAccessService implements CacheAccessService { + + private final BlockCache blockCache; + + /** + * Creates a cache access service backed by the supplied legacy block cache. + * @param blockCache block cache to wrap + */ + public BlockCacheBackedCacheAccessService(BlockCache blockCache) { + this.blockCache = Objects.requireNonNull(blockCache, "blockCache must not be null"); + } + + /** + * Returns the wrapped {@link BlockCache} instance. + * <p> + * This accessor is intended for tests and transitional wiring only. New read/write path code + * should use {@link CacheAccessService} methods instead of unwrapping the legacy cache. + * </p> + * @return wrapped block cache + */ + public BlockCache getBlockCache() { + return blockCache; + } + + /** + * Returns a human-readable service name. + * @return service name + */ + @Override + public String getName() { + return blockCache.getClass().getSimpleName(); + } + + /** + * Fetches a block by delegating to the wrapped {@link BlockCache}. + * @param cacheKey block to fetch + * @param context cache request context + * @return cached block, or {@code null} if not present + */ + @Override + public Cacheable getBlock(BlockCacheKey cacheKey, CacheRequestContext context) { + Objects.requireNonNull(cacheKey, "cacheKey must not be null"); + Objects.requireNonNull(context, "context must not be null"); + + Optional<BlockType> blockType = context.getBlockType(); + if (blockType.isPresent()) { + return blockCache.getBlock(cacheKey, context.isCaching(), context.isRepeat(), + context.isUpdateCacheMetrics(), blockType.get()); + } + return blockCache.getBlock(cacheKey, context.isCaching(), context.isRepeat(), + context.isUpdateCacheMetrics()); + } + + /** + * Caches a block by delegating to the wrapped {@link BlockCache}. + * @param cacheKey block cache key + * @param block block contents + * @param context cache write context + */ + @Override + public void cacheBlock(BlockCacheKey cacheKey, Cacheable block, CacheWriteContext context) { + Objects.requireNonNull(cacheKey, "cacheKey must not be null"); + Objects.requireNonNull(block, "block must not be null"); + Objects.requireNonNull(context, "context must not be null"); + + blockCache.cacheBlock(cacheKey, block, context.isInMemory(), context.isWaitWhenCache()); + } + + /** + * Evicts a single block by delegating to the wrapped {@link BlockCache}. + * @param cacheKey block to remove + * @return {@code true} if the block existed and was removed, {@code false} otherwise + */ + @Override + public boolean evictBlock(BlockCacheKey cacheKey) { + Objects.requireNonNull(cacheKey, "cacheKey must not be null"); + return blockCache.evictBlock(cacheKey); + } + + /** + * Evicts all cached blocks for the given HFile by delegating to the wrapped {@link BlockCache}. + * @param hfileName HFile name + * @return number of blocks removed + */ + @Override + public int evictBlocksByHfileName(String hfileName) { + Objects.requireNonNull(hfileName, "hfileName must not be null"); + return blockCache.evictBlocksByHfileName(hfileName); + } + + /** + * Evicts cached blocks for an HFile range if the wrapped cache supports it. + * @param hfileName HFile name + * @param initOffset inclusive start offset + * @param endOffset inclusive end offset + * @return number of blocks removed + */ + @Override + public int evictBlocksRangeByHfileName(String hfileName, long initOffset, long endOffset) { + Objects.requireNonNull(hfileName, "hfileName must not be null"); + return blockCache.evictBlocksRangeByHfileName(hfileName, initOffset, endOffset); + } + + /** + * Evicts cached blocks for a region if the wrapped cache supports it. + * @param regionName region name + * @return number of blocks removed + */ + @Override + public int evictBlocksByRegionName(String regionName) { + return 0; // BlockCache does not support region-based eviction, so we return 0 to indicate no + // blocks removed Review Comment: nit: please fix the comment line above the return line. ########## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/TopologyBackedCacheAccessService.java: ########## @@ -0,0 +1,476 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import java.util.Objects; +import java.util.Optional; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.BlockType; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.hadoop.hbase.io.hfile.HFileBlock; +import org.apache.yetus.audience.InterfaceAudience; + +/** + * {@link CacheAccessService} implementation backed by {@link CacheTopology} and {@link CacheEngine} + * instances. + * <p> + * This implementation connects the cache access layer to the topology, policy, and engine + * abstractions. {@link CachePlacementAdmissionPolicy} decides whether a block should be admitted, + * where it should be placed, which representation should be used, and whether a hit should trigger + * promotion. {@link CacheTopology} provides tier structure, engine lookup, aggregate statistics, + * and topology-specific promotion mechanics. {@link CacheEngine} performs the actual storage + * operations. + * </p> + * <p> + * This class is the topology-backed counterpart to {@link BlockCacheBackedCacheAccessService}. The + * block-cache-backed implementation is useful for incremental migration with no behavior change. + * This implementation is useful once callers are ready to exercise the new topology and engine + * abstractions directly through {@link CacheAccessService}. + * </p> + * <p> + * Representation conversion is not performed by this initial implementation. This preserves current + * behavior while leaving room for future packed/unpacked or engine-default representation handling. + * </p> + */ [email protected] +public class TopologyBackedCacheAccessService implements CacheAccessService { + + private final CacheTopology topology; + private final CachePlacementAdmissionPolicy policy; + private final CacheTopologyView topologyView; + + /** + * Creates a topology-backed cache access service. + * @param topology cache topology used for tier structure, engine lookup, and promotion mechanics + * @param policy placement and admission policy used for cache access decisions + */ + public TopologyBackedCacheAccessService(CacheTopology topology, + CachePlacementAdmissionPolicy policy) { + this.topology = Objects.requireNonNull(topology, "topology must not be null"); + this.policy = Objects.requireNonNull(policy, "policy must not be null"); + this.topologyView = + Objects.requireNonNull(topology.getView(), "topology view must not be null"); + } + + /** + * Returns the topology used by this service. + * <p> + * This accessor is intended for tests, diagnostics, and transitional wiring. HBase read/write + * path callers should use {@link CacheAccessService} methods instead of accessing topology + * directly. + * </p> + * @return cache topology + */ + public CacheTopology getTopology() { + return topology; + } + + /** + * Returns the placement/admission policy used by this service. + * @return placement/admission policy + */ + public CachePlacementAdmissionPolicy getPolicy() { + return policy; + } + + /** + * Returns the read-only topology view used by policy calls. + * @return read-only topology view + */ + public CacheTopologyView getTopologyView() { + return topologyView; + } + + /** + * Returns a human-readable service name. + * @return service name + */ + @Override + public String getName() { + return topology.getName(); + } + + /** + * Fetches a block by checking topology tiers in lookup order. + * <p> + * The lookup order is defined by {@link CacheTopology#getTiers()}. On a cache hit, this method + * asks the configured {@link CachePlacementAdmissionPolicy} whether the block should be promoted. + * If promotion is requested and the target tier exists, promotion mechanics are delegated to + * {@link CacheTopology#promote(BlockCacheKey, Cacheable, CacheEngine, CacheEngine)}. + * </p> + * @param cacheKey block to fetch + * @param context cache request context + * @return cached block, or {@code null} if not present in any tier + */ + @Override + public Cacheable getBlock(BlockCacheKey cacheKey, CacheRequestContext context) { + Objects.requireNonNull(cacheKey, "cacheKey must not be null"); + Objects.requireNonNull(context, "context must not be null"); + + for (CacheTier tier : topology.getTiers()) { + Optional<CacheEngine> engine = topology.getEngine(tier); + if (engine.isEmpty()) { + continue; + } + + Cacheable block = getBlockFromEngine(engine.get(), cacheKey, context); + if (block != null) { + maybePromote(cacheKey, block, tier, engine.get(), context); + return block; + } + } + + return null; + } + + /** + * Adds a block to the cache using policy-selected target tiers. + * <p> + * This method first asks the configured policy whether the block should be admitted. If admitted, + * the policy selects the target tier or tiers. The block is then inserted into each selected + * engine using {@link CacheEngine#cacheBlock(BlockCacheKey, Cacheable, boolean, boolean)}. + * </p> + * <p> + * The policy's representation decision is intentionally not applied in this initial + * implementation. The current block object is passed through unchanged. + * </p> + * @param cacheKey block cache key + * @param block block contents + * @param context cache write context + */ + @Override + public void cacheBlock(BlockCacheKey cacheKey, Cacheable block, CacheWriteContext context) { + Objects.requireNonNull(cacheKey, "cacheKey must not be null"); + Objects.requireNonNull(block, "block must not be null"); + Objects.requireNonNull(context, "context must not be null"); + + AdmissionDecision admission = + policy.shouldAdmit(cacheKey, block, context, AdmissionPriority.NORMAL, topologyView); + if (!admission.isAdmitted()) { + return; + } + + policy.selectRepresentation(cacheKey, block, context, topologyView); + TierDecision tierDecision = policy.selectTier(cacheKey, block, context, topologyView); + for (CacheTier tier : tierDecision.getTiers()) { Review Comment: should be add a comment that `selectRepresentation` would be default to `CURRENT_HBASE_DEFAULT` ? or even remove this line of `selectRepresentation` ? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
