DeltaEncoder

/**
 * Copyright 2011 The Apache Software Foundation
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.hadoop.hbase.io.deltaencoder;

import java.io.DataInputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.ByteBuffer;

import org.apache.hadoop.io.RawComparator;

/**
 * Encoding of KeyValue. It aims to be fast and efficient
 * using assumptions:
 * - the KeyValue are stored sorted by key
 * - we know the structure of KeyValue
 * - the values are iterated always forward from beginning of block
 * - knowledge of Key Value format
 *
 *
 * It is designed to work fast enough to be feasible as in memory compression.
 */
public interface DeltaEncoder {
  /**
   * Compress KeyValues and write them to output buffer.
   * @param writeHere Where to write compressed data.
   * @param rawKeyValues Source of KeyValue for compression.
   * @throws IOException If there is an error in writeHere.
   */
  public void compressKeyValues(OutputStream writeHere, ByteBuffer rawKeyValues)
      throws IOException;

  /**
   * Uncompress.
   * @param source Compressed stream of KeyValues.
   * @return Uncompressed block of KeyValues.
   * @throws IOException If there is an error in source.
   */
  public ByteBuffer uncompressKeyValues(DataInputStream source)
          throws IOException;

  /**
   * Uncompress.
   * @param source Compressed stream of KeyValues.
   * @param allocateHeaderLength Alloc n bytes for header.
   * @param skipLastBytes Do not copy n last bytes.
   * @return Uncompressed block of KeyValues.
   * @throws IOException If there is an error in source.
   */
  public ByteBuffer uncompressKeyValues(DataInputStream source,
      int allocateHeaderLength, int skipLastBytes)
          throws IOException;

  /**
   * Return first key in block. Useful for indexing.
   * @param block encoded block we want index, the position will not change
   * @return First key in block.
   */
  public ByteBuffer getFirstKeyInBlock(ByteBuffer block);

  /**
   * Create a HFileBlock seeker which find KeyValues within a block.
   * @param comperator what kind of comparison should be used
   * @return A newly created seeker.
   */
  public DeltaEncoderSeeker createSeeker(RawComparator<byte[]> comperator);

  /**
   * An interface which enable to seek while underlying data is encoded.
   *
   * It works on one HFileBlock, but it is reusable. See
   * {@link #setCurrentBuffer(ByteBuffer)}.
   */
  public static interface DeltaEncoderSeeker {
    /**
     * Set on which buffer there will be done seeking.
     * @param buffer Used for seeking.
     */
    public void setCurrentBuffer(ByteBuffer buffer);

    /** @return key at current position */
    public ByteBuffer getKey();
    /** @return value at current position */
    public ByteBuffer getValue();
    /** @return key value at current position. */
    public ByteBuffer getKeyValue();

    /** Set position to beginning of given block */
    public void rewind();

    /**
     * Move to next position
     * @return true on success, false if there is no more positions.
     */
    public boolean next();

    /**
     * Move position to the same key (or one before it).
     * @param key Array where is the key.
     * @param offset Key position in array.
     * @param length Key length in array.
     * @param seekBefore find the key before in case of exact match
     * @return 0 on exact match, 1 on inexact match.
     */
    public int blockSeekTo(byte[] key, int offset, int length,
        boolean seekBefore);
  }
}