ImmutableBytesWritable 源码解析

ImmutableBytesWritable 源码解析【updating…】

1. 源码

package org.apache.hadoop.h .io;

import java.io.IOException;
import java.io.DataInput;
import java.io.DataOutput;
import java.util.Arrays;
import java.util.List;

import org.apache.hadoop.h .classification.InterfaceAudience;
import org.apache.hadoop.h .classification.InterfaceStability;
import org.apache.hadoop.io.BytesWritable;
import org.apache.hadoop.io.WritableComparable;
import org.apache.hadoop.io.WritableComparator;

/**
 * A byte sequence that is usable as a key or value.   d on
 * {@  org.apache.hadoop.io.BytesWritable} only this class is NOT resizable
 * and DOES NOT distinguish between the size of the sequence and the current
 * capacity as {@  org.apache.hadoop.io.BytesWritable} does. Hence its
 * comparatively \'immutable\'. When creating a new instance of this class,
 * the underlying byte [] is not copied, just referenced.  The backing
 * buffer is accessed when we go to serialize.
 */
@InterfaceAudience.Public
@InterfaceStability.Stable
@edu.umd.cs.findbugs.annotations.SuppressWarnings(
    value=\"EQ_CHECK_FOR_OPERAND_NOT_COMPATIBLE_WITH_THIS\",
    justification=\"It has been like this forever\")
public class ImmutableBytesWritable
implements WritableComparable<ImmutableBytesWritable> {
  private byte[] bytes;
  private int offset;
  private int length;

  /**
   * Create a zero-size sequence.
   */
  public ImmutableBytesWritable() {
    super();
  }

  /**
   * Create a ImmutableBytesWritable using the byte array as the initial value.
   * @param bytes This array becomes the backing storage for the  .
   */
  public ImmutableBytesWritable(byte[] bytes) {
    this(bytes, 0, bytes.length);
  }

  /**
   * Set the new ImmutableBytesWritable to the contents of the passed
   * <code>ibw</code>.
   * @param ibw the value to set this ImmutableBytesWritable to.
   */
  public ImmutableBytesWritable(final ImmutableBytesWritable ibw) {
    this(ibw.get(), ibw.getOffset(), ibw.getLength());
  }

  /**
   * Set the value to a given byte range
   * @param bytes the new byte range to set to
   * @param offset the offset in newData to start at
   * @param length the number of bytes in the range
   */
  public ImmutableBytesWritable(final byte[] bytes, final int offset,
      final int length) {
    this.bytes = bytes;
    this.offset = offset;
    this.length = length;
  }

  /**
   * Get the data from the BytesWritable.  
     从BytesWritable 读取数据
	 
   * @return The data is only valid between offset and offset+length.
	 数据仅在offset 和 offset+length处有效
   */
  public byte [] get() {
    if (this.bytes == null) {
      throw new IllegalStateException(\"Uninitialiized. Null constructor \" +
        \"called w/o accompaying readFields invocation\");
    }
    return this.bytes;
  }

  /**
   * @param b Use passed bytes as backing array for this instance.
   */
  public void set(final byte [] b) {
    set(b, 0, b.length);
  }

  /**
   * @param b Use passed bytes as backing array for this instance.
   * @param offset
   * @param length
   */
  public void set(final byte [] b, final int offset, final int length) {
    this.bytes = b;
    this.offset = offset;
    this.length = length;
  }

  /**
   * @return the number of valid bytes in the buffer
   * @deprecated use {@  #getLength()} instead
   */
  @Deprecated
  public int getSize() {
    if (this.bytes == null) {
      throw new IllegalStateException(\"Uninitialiized. Null constructor \" +
        \"called w/o accompaying readFields invocation\");
    }
    return this.length;
  }

  /**
   * @return the number of valid bytes in the buffer
   */
  public int getLength() {
    if (this.bytes == null) {
      throw new IllegalStateException(\"Uninitialiized. Null constructor \" +
        \"called w/o accompaying readFields invocation\");
    }
    return this.length;
  }

  /**
   * @return offset
   */
  public int getOffset(){
    return this.offset;
  }

  @Override
  public void readFields(final DataInput in) throws IOException {
    this.length = in.readInt();
    this.bytes = new byte[this.length];
    in.readFully(this.bytes, 0, this.length);
    this.offset = 0;
  }

  @Override
  public void write(final DataOutput out) throws IOException {
    out.writeInt(this.length);
    out.write(this.bytes, this.offset, this.length);
  }

  // Below methods copied from BytesWritable
  @Override
  public int hashCode() {
    int hash = 1;
    for (int i = offset; i < offset + length; i++)
      hash = (31 * hash) + (int)bytes[i];
    return hash;
  }

  /**
   * Define the sort order of the BytesWritable.
   * @param that The other bytes writable
   * @return Positive if left is bigger than right, 0 if they are equal, and
   *         negative if left is smaller than right.
   */
  @Override
  public int compareTo(ImmutableBytesWritable that) {
    return WritableComparator.compareBytes(
      this.bytes, this.offset, this.length,
      that.bytes, that.offset, that.length);
  }

  /**
   * Compares the bytes in this   to the specified byte array
   * @param that
   * @return Positive if left is bigger than right, 0 if they are equal, and
   *         negative if left is smaller than right.
   */
  public int compareTo(final byte [] that) {
    return WritableComparator.compareBytes(
      this.bytes, this.offset, this.length,
      that, 0, that.length);
  }

  /**
   * @see java.lang. #equals(java.lang. )
   */
  @Override
  public boolean equals(  right_obj) {
    if (right_obj instanceof byte []) {
      return compareTo((byte [])right_obj) == 0;
    }
    if (right_obj instanceof ImmutableBytesWritable) {
      return compareTo((ImmutableBytesWritable)right_obj) == 0;
    }
    return false;
  }

  /**
   * @see java.lang. #toString()
   */
  @Override
  public String toString() {
    StringBuilder sb = new StringBuilder(3*this.length);
    final int endIdx = this.offset + this.length;
    for (int idx = this.offset; idx < endIdx ; idx++) {
      sb.append(\' \');
      String num = Integer.toHexString(0xff & this.bytes[idx]);
      // if it is only one digit, add a leading 0.
      if (num.length() < 2) {
        sb.append(\'0\');
      }
      sb.append(num);
    }
    return sb.length() > 0 ? sb.substring(1) : \"\";
  }

  /** A Comparator optimized for ImmutableBytesWritable.
   */
  @InterfaceAudience.Public
  @InterfaceStability.Stable
  public static class Comparator extends WritableComparator {
    private BytesWritable.Comparator comparator =
      new BytesWritable.Comparator();

    /** constructor */
    public Comparator() {
      super(ImmutableBytesWritable.class);
    }

    /**
     * @see org.apache.hadoop.io.WritableComparator#compare(byte[], int, int, byte[], int, int)
     */
    @Override
    public int compare(byte[] b1, int s1, int l1, byte[] b2, int s2, int l2) {
      return comparator.compare(b1, s1, l1, b2, s2, l2);
    }
  }

  static { // register this comparator
    WritableComparator.define(ImmutableBytesWritable.class, new Comparator());
  }

  /**
   * @param array List of byte [].
   * @return Array of byte [].
   */
  public static byte [][] toArray(final List<byte []> array) {
    // List#toArray doesn\'t work on lists of byte [].
    byte[][] results = new byte[array.size()][];
    for (int i = 0; i < array.size(); i++) {
      results[i] = array.get(i);
    }
    return results;
  }

  /**
   * Returns a copy of the bytes referred to by this writable
   */
  public byte[] copyBytes() {
    return Arrays.copyOfRange(bytes, offset, offset+length);
  }
}