View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with this
4    * work for additional information regarding copyright ownership. The ASF
5    * licenses this file to you under the Apache License, Version 2.0 (the
6    * "License"); you may not use this file except in compliance with the License.
7    * You may obtain a copy of the License at
8    *
9    * http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14   * License for the specific language governing permissions and limitations
15   * under the License.
16   */
17  package org.apache.hadoop.hbase.io.hfile;
18  
19  import java.io.DataOutputStream;
20  import java.io.IOException;
21  
22  import org.apache.hadoop.classification.InterfaceAudience;
23  import org.apache.hadoop.hbase.Cell;
24  import org.apache.hadoop.hbase.io.encoding.DataBlockEncoding;
25  import org.apache.hadoop.hbase.io.encoding.HFileBlockDecodingContext;
26  import org.apache.hadoop.hbase.io.encoding.HFileBlockEncodingContext;
27  import org.apache.hadoop.hbase.util.Bytes;
28  
29  /**
30   * Controls what kind of data block encoding is used. If data block encoding is
31   * not set or the given block is not a data block (encoded or not), methods
32   * should just return the unmodified block.
33   */
34  @InterfaceAudience.Private
35  public interface HFileDataBlockEncoder {
36    /** Type of encoding used for data blocks in HFile. Stored in file info. */
37    byte[] DATA_BLOCK_ENCODING = Bytes.toBytes("DATA_BLOCK_ENCODING");
38  
39    /**
40     * Starts encoding for a block of KeyValues. Call
41     * {@link #endBlockEncoding(HFileBlockEncodingContext, DataOutputStream, byte[], BlockType)}
42     * to finish encoding of a block.
43     * @param encodingCtx
44     * @param out
45     * @throws IOException
46     */
47    void startBlockEncoding(HFileBlockEncodingContext encodingCtx, DataOutputStream out)
48        throws IOException;
49  
50    /**
51     * Encodes a KeyValue.
52     * @param cell
53     * @param encodingCtx
54     * @param out
55     * @return unencoded kv size
56     * @throws IOException
57     */
58    int encode(Cell cell, HFileBlockEncodingContext encodingCtx, DataOutputStream out)
59        throws IOException;
60  
61    /**
62     * Ends encoding for a block of KeyValues. Gives a chance for the encoder to do the finishing
63     * stuff for the encoded block. It must be called at the end of block encoding.
64     * @param encodingCtx
65     * @param out
66     * @param uncompressedBytesWithHeader
67     * @param blockType
68     * @throws IOException
69     */
70    void endBlockEncoding(HFileBlockEncodingContext encodingCtx, DataOutputStream out,
71        byte[] uncompressedBytesWithHeader, BlockType blockType) throws IOException;
72  
73    /**
74     * Decides whether we should use a scanner over encoded blocks.
75     * @return Whether to use encoded scanner.
76     */
77    boolean useEncodedScanner();
78  
79    /**
80     * Save metadata in HFile which will be written to disk
81     * @param writer writer for a given HFile
82     * @exception IOException on disk problems
83     */
84    void saveMetadata(HFile.Writer writer)
85        throws IOException;
86  
87    /** @return the data block encoding */
88    DataBlockEncoding getDataBlockEncoding();
89  
90    /**
91     * @return the effective in-cache data block encoding, taking into account
92     *         whether we are doing a compaction.
93     */
94    public DataBlockEncoding getEffectiveEncodingInCache(boolean isCompaction);
95  
96    /**
97     * Create an encoder specific encoding context object for writing. And the
98     * encoding context should also perform compression if compressionAlgorithm is
99     * valid.
100    *
101    * @param headerBytes header bytes
102    * @param fileContext HFile meta data
103    * @return a new {@link HFileBlockEncodingContext} object
104    */
105   HFileBlockEncodingContext newDataBlockEncodingContext(byte[] headerBytes,
106       HFileContext fileContext);
107 
108   /**
109    * create a encoder specific decoding context for reading. And the
110    * decoding context should also do decompression if compressionAlgorithm
111    * is valid.
112    *
113    * @param fileContext - HFile meta data
114    * @return a new {@link HFileBlockDecodingContext} object
115    */
116   HFileBlockDecodingContext newDataBlockDecodingContext(HFileContext fileContext);
117 }