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.util;
20  
21  import java.nio.ByteBuffer;
22  
23  import org.apache.hadoop.hbase.classification.InterfaceAudience;
24  import org.apache.hadoop.hbase.classification.InterfaceStability;
25  
26  /**
27   * <p>
28   * Extends {@link ByteRange} with additional methods to support tracking a
29   * consumers position within the viewport. The API is extended with methods
30   * {@link #get()} and {@link #put(byte)} for interacting with the backing
31   * array from the current position forward. This frees the caller from managing
32   * their own index into the array.
33   * </p>
34   * <p>
35   * Designed to be a slimmed-down, mutable alternative to {@link ByteBuffer}.
36   * </p>
37   */
38  @InterfaceAudience.Public
39  @InterfaceStability.Evolving
40  public interface PositionedByteRange extends ByteRange {
41  
42    // net new API is here.
43  
44    /**
45     * The current {@code position} marker. This valuae is 0-indexed, relative to
46     * the beginning of the range.
47     */
48    public int getPosition();
49  
50    /**
51     * Update the {@code position} index. May not be greater than {@code length}.
52     * @param position the new position in this range.
53     * @return this.
54     */
55    public PositionedByteRange setPosition(int position);
56  
57    /**
58     * The number of bytes remaining between position and the end of the range.
59     */
60    public int getRemaining();
61  
62    /**
63     * Retrieve the next byte from this range without incrementing position.
64     */
65    public byte peek();
66  
67    /**
68     * Retrieve the next byte from this range.
69     */
70    public byte get();
71  
72    /**
73     * Fill {@code dst} with bytes from the range, starting from {@code position}.
74     * This range's {@code position} is incremented by the length of {@code dst},
75     * the number of bytes copied.
76     * @param dst the destination of the copy.
77     * @return this.
78     */
79    public PositionedByteRange get(byte[] dst);
80  
81    /**
82     * Fill {@code dst} with bytes from the range, starting from the current
83     * {@code position}. {@code length} bytes are copied into {@code dst},
84     * starting at {@code offset}. This range's {@code position} is incremented
85     * by the number of bytes copied.
86     * @param dst the destination of the copy.
87     * @param offset the offset into {@code dst} to start the copy.
88     * @param length the number of bytes to copy into {@code dst}.
89     * @return this.
90     */
91    public PositionedByteRange get(byte[] dst, int offset, int length);
92  
93    /**
94     * Store {@code val} at the next position in this range.
95     * @param val the new value.
96     * @return this.
97     */
98    public PositionedByteRange put(byte val);
99  
100   /**
101    * Store the content of {@code val} in this range, starting at the next position.
102    * @param val the new value.
103    * @return this.
104    */
105   public PositionedByteRange put(byte[] val);
106 
107   /**
108    * Store {@code length} bytes from {@code val} into this range. Bytes from
109    * {@code val} are copied starting at {@code offset} into the range, starting at
110    * the current position.
111    * @param val the new value.
112    * @param offset the offset in {@code val} from which to start copying.
113    * @param length the number of bytes to copy from {@code val}.
114    * @return this.
115    */
116   public PositionedByteRange put(byte[] val, int offset, int length);
117 
118   // override parent interface declarations to return this interface.
119 
120   @Override
121   public PositionedByteRange unset();
122 
123   @Override
124   public PositionedByteRange set(int capacity);
125 
126   @Override
127   public PositionedByteRange set(byte[] bytes);
128 
129   @Override
130   public PositionedByteRange set(byte[] bytes, int offset, int length);
131 
132   @Override
133   public PositionedByteRange setOffset(int offset);
134 
135   @Override
136   public PositionedByteRange setLength(int length);
137 
138   @Override
139   public PositionedByteRange get(int index, byte[] dst);
140 
141   @Override
142   public PositionedByteRange get(int index, byte[] dst, int offset, int length);
143 
144   @Override
145   public PositionedByteRange put(int index, byte val);
146 
147   @Override
148   public PositionedByteRange put(int index, byte[] val);
149 
150   @Override
151   public PositionedByteRange put(int index, byte[] val, int offset, int length);
152 
153   @Override
154   public PositionedByteRange deepCopy();
155 
156   @Override
157   public PositionedByteRange shallowCopy();
158 
159   @Override
160   public PositionedByteRange shallowCopySubRange(int innerOffset, int copyLength);
161 }