View Javadoc

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