View Javadoc

1   /**
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  package org.apache.hadoop.hbase.io.hfile;
20  
21  import java.io.IOException;
22  import java.util.List;
23  
24  import org.apache.hadoop.classification.InterfaceAudience;
25  import org.apache.hadoop.conf.Configuration;
26  
27  /**
28   * Block cache interface. Anything that implements the {@link Cacheable}
29   * interface can be put in the cache.
30   */
31  @InterfaceAudience.Private
32  public interface BlockCache {
33    /**
34     * Add block to cache.
35     * @param cacheKey The block's cache key.
36     * @param buf The block contents wrapped in a ByteBuffer.
37     * @param inMemory Whether block should be treated as in-memory
38     */
39    void cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean inMemory);
40  
41    /**
42     * Add block to cache (defaults to not in-memory).
43     * @param cacheKey The block's cache key.
44     * @param buf The object to cache.
45     */
46    void cacheBlock(BlockCacheKey cacheKey, Cacheable buf);
47  
48    /**
49     * Fetch block from cache.
50     * @param cacheKey Block to fetch.
51     * @param caching Whether this request has caching enabled (used for stats)
52     * @param repeat Whether this is a repeat lookup for the same block
53     *        (used to avoid double counting cache misses when doing double-check locking)
54     * @param updateCacheMetrics Whether to update cache metrics or not
55     * @return Block or null if block is not in 2 cache.
56     */
57    Cacheable getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat,
58      boolean updateCacheMetrics);
59  
60    /**
61     * Evict block from cache.
62     * @param cacheKey Block to evict
63     * @return true if block existed and was evicted, false if not
64     */
65    boolean evictBlock(BlockCacheKey cacheKey);
66  
67    /**
68     * Evicts all blocks for the given HFile.
69     *
70     * @return the number of blocks evicted
71     */
72    int evictBlocksByHfileName(String hfileName);
73  
74    /**
75     * Get the statistics for this block cache.
76     * @return Stats
77     */
78    CacheStats getStats();
79  
80    /**
81     * Shutdown the cache.
82     */
83    void shutdown();
84  
85    /**
86     * Returns the total size of the block cache, in bytes.
87     * @return size of cache, in bytes
88     */
89    long size();
90  
91    /**
92     * Returns the free size of the block cache, in bytes.
93     * @return free space in cache, in bytes
94     */
95    long getFreeSize();
96  
97    /**
98     * Returns the occupied size of the block cache, in bytes.
99     * @return occupied space in cache, in bytes
100    */
101   long getCurrentSize();
102 
103   /**
104    * Returns the number of blocks that have been evicted.
105    * @return number of evicted blocks
106    */
107   long getEvictedCount();
108 
109   /**
110    * Returns the number of blocks currently cached in the block cache.
111    * @return number of blocks in the cache
112    */
113   long getBlockCount();
114 
115   /**
116    * Performs a BlockCache summary and returns a List of BlockCacheColumnFamilySummary objects.
117    * This method could be fairly heavyweight in that it evaluates the entire HBase file-system
118    * against what is in the RegionServer BlockCache.
119    * <br><br>
120    * The contract of this interface is to return the List in sorted order by Table name, then
121    * ColumnFamily.
122    *
123    * @param conf HBaseConfiguration
124    * @return List of BlockCacheColumnFamilySummary
125    * @throws IOException exception
126    */
127   List<BlockCacheColumnFamilySummary> getBlockCacheColumnFamilySummaries(Configuration conf) throws IOException;
128 }