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     * @return Block or null if block is not in 2 cache.
55     * @see HFileReaderV2#readBlock(long, long, boolean, boolean, boolean, BlockType)
56     */
57    Cacheable getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat);
58  
59    /**
60     * Evict block from cache.
61     * @param cacheKey Block to evict
62     * @return true if block existed and was evicted, false if not
63     */
64    boolean evictBlock(BlockCacheKey cacheKey);
65  
66    /**
67     * Evicts all blocks for the given HFile.
68     *
69     * @return the number of blocks evicted
70     */
71    int evictBlocksByHfileName(String hfileName);
72  
73    /**
74     * Get the statistics for this block cache.
75     * @return Stats
76     */
77    CacheStats getStats();
78  
79    /**
80     * Shutdown the cache.
81     */
82    void shutdown();
83  
84    /**
85     * Returns the total size of the block cache, in bytes.
86     * @return size of cache, in bytes
87     */
88    long size();
89  
90    /**
91     * Returns the free size of the block cache, in bytes.
92     * @return free space in cache, in bytes
93     */
94    long getFreeSize();
95  
96    /**
97     * Returns the occupied size of the block cache, in bytes.
98     * @return occupied space in cache, in bytes
99     */
100   long getCurrentSize();
101 
102   /**
103    * Returns the number of blocks that have been evicted.
104    * @return number of evicted blocks
105    */
106   long getEvictedCount();
107 
108   /**
109    * Returns the number of blocks currently cached in the block cache.
110    * @return number of blocks in the cache
111    */
112   long getBlockCount();
113 
114   /**
115    * Performs a BlockCache summary and returns a List of BlockCacheColumnFamilySummary objects.
116    * This method could be fairly heavyweight in that it evaluates the entire HBase file-system
117    * against what is in the RegionServer BlockCache.
118    * <br><br>
119    * The contract of this interface is to return the List in sorted order by Table name, then
120    * ColumnFamily.
121    *
122    * @param conf HBaseConfiguration
123    * @return List of BlockCacheColumnFamilySummary
124    * @throws IOException exception
125    */
126   List<BlockCacheColumnFamilySummary> getBlockCacheColumnFamilySummaries(Configuration conf) throws IOException;
127 }