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