View Javadoc

1   /**
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.apache.hadoop.hbase.io;
20  
21  import java.io.DataInput;
22  import java.io.DataOutput;
23  import java.io.IOException;
24  import java.util.Arrays;
25  import java.util.List;
26  
27  import org.apache.hadoop.hbase.classification.InterfaceAudience;
28  import org.apache.hadoop.hbase.classification.InterfaceStability;
29  import org.apache.hadoop.io.BytesWritable;
30  import org.apache.hadoop.io.WritableComparable;
31  import org.apache.hadoop.io.WritableComparator;
32  
33  /**
34   * A byte sequence that is usable as a key or value.  Based on
35   * {@link org.apache.hadoop.io.BytesWritable} only this class is NOT resizable
36   * and DOES NOT distinguish between the size of the sequence and the current
37   * capacity as {@link org.apache.hadoop.io.BytesWritable} does. Hence its
38   * comparatively 'immutable'. When creating a new instance of this class,
39   * the underlying byte [] is not copied, just referenced.  The backing
40   * buffer is accessed when we go to serialize.
41   */
42  @InterfaceAudience.Public
43  @InterfaceStability.Stable
44  @edu.umd.cs.findbugs.annotations.SuppressWarnings(
45      value="EQ_CHECK_FOR_OPERAND_NOT_COMPATIBLE_WITH_THIS",
46      justification="It has been like this forever")
47  public class ImmutableBytesWritable
48  implements WritableComparable<ImmutableBytesWritable> {
49    private byte[] bytes;
50    private int offset;
51    private int length;
52  
53    /**
54     * Create a zero-size sequence.
55     */
56    public ImmutableBytesWritable() {
57      super();
58    }
59  
60    /**
61     * Create a ImmutableBytesWritable using the byte array as the initial value.
62     * @param bytes This array becomes the backing storage for the object.
63     */
64    public ImmutableBytesWritable(byte[] bytes) {
65      this(bytes, 0, bytes.length);
66    }
67  
68    /**
69     * Set the new ImmutableBytesWritable to the contents of the passed
70     * <code>ibw</code>.
71     * @param ibw the value to set this ImmutableBytesWritable to.
72     */
73    public ImmutableBytesWritable(final ImmutableBytesWritable ibw) {
74      this(ibw.get(), ibw.getOffset(), ibw.getLength());
75    }
76  
77    /**
78     * Set the value to a given byte range
79     * @param bytes the new byte range to set to
80     * @param offset the offset in newData to start at
81     * @param length the number of bytes in the range
82     */
83    public ImmutableBytesWritable(final byte[] bytes, final int offset,
84        final int length) {
85      this.bytes = bytes;
86      this.offset = offset;
87      this.length = length;
88    }
89  
90    /**
91     * Get the data from the BytesWritable.
92     * @return The data is only valid between offset and offset+length.
93     */
94    public byte [] get() {
95      if (this.bytes == null) {
96        throw new IllegalStateException("Uninitialiized. Null constructor " +
97          "called w/o accompaying readFields invocation");
98      }
99      return this.bytes;
100   }
101 
102   /**
103    * @param b Use passed bytes as backing array for this instance.
104    */
105   public void set(final byte [] b) {
106     set(b, 0, b.length);
107   }
108 
109   /**
110    * @param b Use passed bytes as backing array for this instance.
111    * @param offset
112    * @param length
113    */
114   public void set(final byte [] b, final int offset, final int length) {
115     this.bytes = b;
116     this.offset = offset;
117     this.length = length;
118   }
119 
120   /**
121    * @return the number of valid bytes in the buffer
122    * @deprecated use {@link #getLength()} instead
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   public void readFields(final DataInput in) throws IOException {
152     this.length = in.readInt();
153     this.bytes = new byte[this.length];
154     in.readFully(this.bytes, 0, this.length);
155     this.offset = 0;
156   }
157 
158   public void write(final DataOutput out) throws IOException {
159     out.writeInt(this.length);
160     out.write(this.bytes, this.offset, this.length);
161   }
162 
163   // Below methods copied from BytesWritable
164   @Override
165   public int hashCode() {
166     int hash = 1;
167     for (int i = offset; i < offset + length; i++)
168       hash = (31 * hash) + (int)bytes[i];
169     return hash;
170   }
171 
172   /**
173    * Define the sort order of the BytesWritable.
174    * @param that The other bytes writable
175    * @return Positive if left is bigger than right, 0 if they are equal, and
176    *         negative if left is smaller than right.
177    */
178   public int compareTo(ImmutableBytesWritable that) {
179     return WritableComparator.compareBytes(
180       this.bytes, this.offset, this.length,
181       that.bytes, that.offset, that.length);
182   }
183 
184   /**
185    * Compares the bytes in this object to the specified byte array
186    * @param that
187    * @return Positive if left is bigger than right, 0 if they are equal, and
188    *         negative if left is smaller than right.
189    */
190   public int compareTo(final byte [] that) {
191     return WritableComparator.compareBytes(
192       this.bytes, this.offset, this.length,
193       that, 0, that.length);
194   }
195 
196   /**
197    * @see java.lang.Object#equals(java.lang.Object)
198    */
199   @Override
200   public boolean equals(Object right_obj) {
201     if (right_obj instanceof byte []) {
202       return compareTo((byte [])right_obj) == 0;
203     }
204     if (right_obj instanceof ImmutableBytesWritable) {
205       return compareTo((ImmutableBytesWritable)right_obj) == 0;
206     }
207     return false;
208   }
209 
210   /**
211    * @see java.lang.Object#toString()
212    */
213   @Override
214   public String toString() {
215     StringBuilder sb = new StringBuilder(3*this.length);
216     final int endIdx = this.offset + this.length;
217     for (int idx = this.offset; idx < endIdx ; idx++) {
218       sb.append(' ');
219       String num = Integer.toHexString(0xff & this.bytes[idx]);
220       // if it is only one digit, add a leading 0.
221       if (num.length() < 2) {
222         sb.append('0');
223       }
224       sb.append(num);
225     }
226     return sb.length() > 0 ? sb.substring(1) : "";
227   }
228 
229   /** A Comparator optimized for ImmutableBytesWritable.
230    */
231   public static class Comparator extends WritableComparator {
232     private BytesWritable.Comparator comparator =
233       new BytesWritable.Comparator();
234 
235     /** constructor */
236     public Comparator() {
237       super(ImmutableBytesWritable.class);
238     }
239 
240     /**
241      * @see org.apache.hadoop.io.WritableComparator#compare(byte[], int, int, byte[], int, int)
242      */
243     @Override
244     public int compare(byte[] b1, int s1, int l1, byte[] b2, int s2, int l2) {
245       return comparator.compare(b1, s1, l1, b2, s2, l2);
246     }
247   }
248 
249   static { // register this comparator
250     WritableComparator.define(ImmutableBytesWritable.class, new Comparator());
251   }
252 
253   /**
254    * @param array List of byte [].
255    * @return Array of byte [].
256    */
257   public static byte [][] toArray(final List<byte []> array) {
258     // List#toArray doesn't work on lists of byte [].
259     byte[][] results = new byte[array.size()][];
260     for (int i = 0; i < array.size(); i++) {
261       results[i] = array.get(i);
262     }
263     return results;
264   }
265 
266   /**
267    * Returns a copy of the bytes referred to by this writable
268    */
269   public byte[] copyBytes() {
270     return Arrays.copyOfRange(bytes, offset, offset+length);
271   }
272 }