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 */
018
019package org.apache.hadoop.hbase.io;
020
021import java.io.DataInput;
022import java.io.DataOutput;
023import java.io.IOException;
024import java.util.Arrays;
025import java.util.List;
026
027import org.apache.hadoop.io.BytesWritable;
028import org.apache.hadoop.io.WritableComparable;
029import org.apache.hadoop.io.WritableComparator;
030import org.apache.yetus.audience.InterfaceAudience;
031
032/**
033 * A byte sequence that is usable as a key or value.  Based on
034 * {@link org.apache.hadoop.io.BytesWritable} only this class is NOT resizable
035 * and DOES NOT distinguish between the size of the sequence and the current
036 * capacity as {@link org.apache.hadoop.io.BytesWritable} does. Hence its
037 * comparatively 'immutable'. When creating a new instance of this class,
038 * the underlying byte [] is not copied, just referenced.  The backing
039 * buffer is accessed when we go to serialize.
040 */
041@InterfaceAudience.Public
042@edu.umd.cs.findbugs.annotations.SuppressWarnings(
043    value="EQ_CHECK_FOR_OPERAND_NOT_COMPATIBLE_WITH_THIS",
044    justification="It has been like this forever")
045public class ImmutableBytesWritable
046implements WritableComparable<ImmutableBytesWritable> {
047  private byte[] bytes;
048  private int offset;
049  private int length;
050
051  /**
052   * Create a zero-size sequence.
053   */
054  public ImmutableBytesWritable() {
055    super();
056  }
057
058  /**
059   * Create a ImmutableBytesWritable using the byte array as the initial value.
060   * @param bytes This array becomes the backing storage for the object.
061   */
062  public ImmutableBytesWritable(byte[] bytes) {
063    this(bytes, 0, bytes.length);
064  }
065
066  /**
067   * Set the new ImmutableBytesWritable to the contents of the passed
068   * <code>ibw</code>.
069   * @param ibw the value to set this ImmutableBytesWritable to.
070   */
071  public ImmutableBytesWritable(final ImmutableBytesWritable ibw) {
072    this(ibw.get(), ibw.getOffset(), ibw.getLength());
073  }
074
075  /**
076   * Set the value to a given byte range
077   * @param bytes the new byte range to set to
078   * @param offset the offset in newData to start at
079   * @param length the number of bytes in the range
080   */
081  public ImmutableBytesWritable(final byte[] bytes, final int offset,
082      final int length) {
083    this.bytes = bytes;
084    this.offset = offset;
085    this.length = length;
086  }
087
088  /**
089   * Get the data from the BytesWritable.
090   * @return The data is only valid between offset and offset+length.
091   */
092  public byte [] get() {
093    if (this.bytes == null) {
094      throw new IllegalStateException("Uninitialiized. Null constructor " +
095        "called w/o accompaying readFields invocation");
096    }
097    return this.bytes;
098  }
099
100  /**
101   * @param b Use passed bytes as backing array for this instance.
102   */
103  public void set(final byte [] b) {
104    set(b, 0, b.length);
105  }
106
107  /**
108   * @param b Use passed bytes as backing array for this instance.
109   * @param offset
110   * @param length
111   */
112  public void set(final byte [] b, final int offset, final int length) {
113    this.bytes = b;
114    this.offset = offset;
115    this.length = length;
116  }
117
118  /**
119   * @return the number of valid bytes in the buffer
120   * @deprecated since 0.98.5. Use {@link #getLength()} instead
121   * @see #getLength()
122   * @see <a href="https://issues.apache.org/jira/browse/HBASE-11561">HBASE-11561</a>
123   */
124  @Deprecated
125  public int getSize() {
126    if (this.bytes == null) {
127      throw new IllegalStateException("Uninitialiized. Null constructor " +
128        "called w/o accompaying readFields invocation");
129    }
130    return this.length;
131  }
132
133  /**
134   * @return the number of valid bytes in the buffer
135   */
136  public int getLength() {
137    if (this.bytes == null) {
138      throw new IllegalStateException("Uninitialiized. Null constructor " +
139        "called w/o accompaying readFields invocation");
140    }
141    return this.length;
142  }
143
144  /**
145   * @return offset
146   */
147  public int getOffset(){
148    return this.offset;
149  }
150
151  @Override
152  public void readFields(final DataInput in) throws IOException {
153    this.length = in.readInt();
154    this.bytes = new byte[this.length];
155    in.readFully(this.bytes, 0, this.length);
156    this.offset = 0;
157  }
158
159  @Override
160  public void write(final DataOutput out) throws IOException {
161    out.writeInt(this.length);
162    out.write(this.bytes, this.offset, this.length);
163  }
164
165  // Below methods copied from BytesWritable
166  @Override
167  public int hashCode() {
168    int hash = 1;
169    for (int i = offset; i < offset + length; i++)
170      hash = (31 * hash) + (int)bytes[i];
171    return hash;
172  }
173
174  /**
175   * Define the sort order of the BytesWritable.
176   * @param that The other bytes writable
177   * @return Positive if left is bigger than right, 0 if they are equal, and
178   *         negative if left is smaller than right.
179   */
180  @Override
181  public int compareTo(ImmutableBytesWritable that) {
182    return WritableComparator.compareBytes(
183      this.bytes, this.offset, this.length,
184      that.bytes, that.offset, that.length);
185  }
186
187  /**
188   * Compares the bytes in this object to the specified byte array
189   * @param that
190   * @return Positive if left is bigger than right, 0 if they are equal, and
191   *         negative if left is smaller than right.
192   */
193  public int compareTo(final byte [] that) {
194    return WritableComparator.compareBytes(
195      this.bytes, this.offset, this.length,
196      that, 0, that.length);
197  }
198
199  /**
200   * @see java.lang.Object#equals(java.lang.Object)
201   */
202  @Override
203  public boolean equals(Object right_obj) {
204    if (right_obj instanceof byte []) {
205      return compareTo((byte [])right_obj) == 0;
206    }
207    if (right_obj instanceof ImmutableBytesWritable) {
208      return compareTo((ImmutableBytesWritable)right_obj) == 0;
209    }
210    return false;
211  }
212
213  /**
214   * @see java.lang.Object#toString()
215   */
216  @Override
217  public String toString() {
218    StringBuilder sb = new StringBuilder(3*this.length);
219    final int endIdx = this.offset + this.length;
220    for (int idx = this.offset; idx < endIdx ; idx++) {
221      sb.append(' ');
222      String num = Integer.toHexString(0xff & this.bytes[idx]);
223      // if it is only one digit, add a leading 0.
224      if (num.length() < 2) {
225        sb.append('0');
226      }
227      sb.append(num);
228    }
229    return sb.length() > 0 ? sb.substring(1) : "";
230  }
231
232  /** A Comparator optimized for ImmutableBytesWritable.
233   */
234  @InterfaceAudience.Public
235  public static class Comparator extends WritableComparator {
236    private BytesWritable.Comparator comparator =
237      new BytesWritable.Comparator();
238
239    /** constructor */
240    public Comparator() {
241      super(ImmutableBytesWritable.class);
242    }
243
244    /**
245     * @see org.apache.hadoop.io.WritableComparator#compare(byte[], int, int, byte[], int, int)
246     */
247    @Override
248    public int compare(byte[] b1, int s1, int l1, byte[] b2, int s2, int l2) {
249      return comparator.compare(b1, s1, l1, b2, s2, l2);
250    }
251  }
252
253  static { // register this comparator
254    WritableComparator.define(ImmutableBytesWritable.class, new Comparator());
255  }
256
257  /**
258   * @param array List of byte [].
259   * @return Array of byte [].
260   */
261  public static byte [][] toArray(final List<byte []> array) {
262    // List#toArray doesn't work on lists of byte [].
263    byte[][] results = new byte[array.size()][];
264    for (int i = 0; i < array.size(); i++) {
265      results[i] = array.get(i);
266    }
267    return results;
268  }
269
270  /**
271   * Returns a copy of the bytes referred to by this writable
272   */
273  public byte[] copyBytes() {
274    return Arrays.copyOfRange(bytes, offset, offset+length);
275  }
276}