001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.io.hfile;
019
020import java.io.DataOutputStream;
021import java.io.IOException;
022import org.apache.hadoop.conf.Configuration;
023import org.apache.hadoop.hbase.Cell;
024import org.apache.hadoop.hbase.io.encoding.DataBlockEncoding;
025import org.apache.hadoop.hbase.io.encoding.HFileBlockDecodingContext;
026import org.apache.hadoop.hbase.io.encoding.HFileBlockEncodingContext;
027import org.apache.hadoop.hbase.util.Bytes;
028import org.apache.yetus.audience.InterfaceAudience;
029
030/**
031 * Controls what kind of data block encoding is used. If data block encoding is not set or the given
032 * block is not a data block (encoded or not), methods should just return the unmodified block.
033 */
034@InterfaceAudience.Private
035public interface HFileDataBlockEncoder {
036  /** Type of encoding used for data blocks in HFile. Stored in file info. */
037  byte[] DATA_BLOCK_ENCODING = Bytes.toBytes("DATA_BLOCK_ENCODING");
038
039  /**
040   * Starts encoding for a block of KeyValues. Call
041   * {@link #endBlockEncoding(HFileBlockEncodingContext, DataOutputStream, byte[], BlockType)} to
042   * finish encoding of a block. nnn
043   */
044  void startBlockEncoding(HFileBlockEncodingContext encodingCtx, DataOutputStream out)
045    throws IOException;
046
047  /**
048   * Encodes a KeyValue. nnnn
049   */
050  void encode(Cell cell, HFileBlockEncodingContext encodingCtx, DataOutputStream out)
051    throws IOException;
052
053  /**
054   * Ends encoding for a block of KeyValues. Gives a chance for the encoder to do the finishing
055   * stuff for the encoded block. It must be called at the end of block encoding. nnnnn
056   */
057  void endBlockEncoding(HFileBlockEncodingContext encodingCtx, DataOutputStream out,
058    byte[] uncompressedBytesWithHeader, BlockType blockType) throws IOException;
059
060  /**
061   * Decides whether we should use a scanner over encoded blocks.
062   * @return Whether to use encoded scanner.
063   */
064  boolean useEncodedScanner();
065
066  /**
067   * Save metadata in HFile which will be written to disk
068   * @param writer writer for a given HFile
069   * @exception IOException on disk problems
070   */
071  void saveMetadata(HFile.Writer writer) throws IOException;
072
073  /** Returns the data block encoding */
074  DataBlockEncoding getDataBlockEncoding();
075
076  /**
077   * @return the effective in-cache data block encoding, taking into account whether we are doing a
078   *         compaction.
079   */
080  public DataBlockEncoding getEffectiveEncodingInCache(boolean isCompaction);
081
082  /**
083   * Create an encoder specific encoding context object for writing. And the encoding context should
084   * also perform compression if compressionAlgorithm is valid.
085   * @param conf        store configuration
086   * @param headerBytes header bytes
087   * @param fileContext HFile meta data
088   * @return a new {@link HFileBlockEncodingContext} object
089   */
090  HFileBlockEncodingContext newDataBlockEncodingContext(Configuration conf, byte[] headerBytes,
091    HFileContext fileContext);
092
093  /**
094   * create a encoder specific decoding context for reading. And the decoding context should also do
095   * decompression if compressionAlgorithm is valid.
096   * @param conf        store configuration
097   * @param fileContext - HFile meta data
098   * @return a new {@link HFileBlockDecodingContext} object
099   */
100  HFileBlockDecodingContext newDataBlockDecodingContext(Configuration conf,
101    HFileContext fileContext);
102}