View Javadoc

1   /**
2    * Copyright 2010 The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase.client;
21  
22  import java.io.IOException;
23  import java.util.List;
24  
25  import org.apache.hadoop.conf.Configuration;
26  import org.apache.hadoop.hbase.HTableDescriptor;
27  import org.apache.hadoop.hbase.KeyValue;
28  
29  /**
30   * Used to communicate with a single HBase table.
31   *
32   * @since 0.21.0
33   */
34  public interface HTableInterface {
35  
36    /**
37     * Gets the name of this table.
38     *
39     * @return the table name.
40     */
41    byte[] getTableName();
42  
43    /**
44     * Returns the {@link Configuration} object used by this instance.
45     * <p>
46     * The reference returned is not a copy, so any change made to it will
47     * affect this instance.
48     */
49    Configuration getConfiguration();
50  
51    /**
52     * Gets the {@link HTableDescriptor table descriptor} for this table.
53     * @throws IOException if a remote or network exception occurs.
54     */
55    HTableDescriptor getTableDescriptor() throws IOException;
56  
57    /**
58     * Test for the existence of columns in the table, as specified in the Get.
59     * <p>
60     *
61     * This will return true if the Get matches one or more keys, false if not.
62     * <p>
63     *
64     * This is a server-side call so it prevents any data from being transfered to
65     * the client.
66     *
67     * @param get the Get
68     * @return true if the specified Get matches one or more keys, false if not
69     * @throws IOException e
70     */
71    boolean exists(Get get) throws IOException;
72  
73    /**
74     * Method that does a batch call on Deletes, Gets and Puts.
75     *
76     * @param actions list of Get, Put, Delete objects
77     * @param results Empty Object[], same size as actions. Provides access to partial
78     *                results, in case an exception is thrown. A null in the result array means that
79     *                the call for that action failed, even after retries
80     * @throws IOException
81     * @since 0.90.0
82     */
83    void batch(final List<Row> actions, final Object[] results) throws IOException, InterruptedException;
84  
85    /**
86     * Method that does a batch call on Deletes, Gets and Puts.
87     *
88     *
89     * @param actions list of Get, Put, Delete objects
90     * @return the results from the actions. A null in the return array means that
91     *         the call for that action failed, even after retries
92     * @throws IOException
93     * @since 0.90.0
94     */
95    Object[] batch(final List<Row> actions) throws IOException, InterruptedException;
96  
97    /**
98     * Extracts certain cells from a given row.
99     * @param get The object that specifies what data to fetch and from which row.
100    * @return The data coming from the specified row, if it exists.  If the row
101    * specified doesn't exist, the {@link Result} instance returned won't
102    * contain any {@link KeyValue}, as indicated by {@link Result#isEmpty()}.
103    * @throws IOException if a remote or network exception occurs.
104    * @since 0.20.0
105    */
106   Result get(Get get) throws IOException;
107 
108   /**
109    * Extracts certain cells from the given rows, in batch.
110    *
111    * @param gets The objects that specify what data to fetch and from which rows.
112    *
113    * @return The data coming from the specified rows, if it exists.  If the row
114    *         specified doesn't exist, the {@link Result} instance returned won't
115    *         contain any {@link KeyValue}, as indicated by {@link Result#isEmpty()}.
116    *         A null in the return array means that the get operation for that
117    *         Get failed, even after retries.
118    * @throws IOException if a remote or network exception occurs.
119    *
120    * @since 0.90.0
121    */
122   Result[] get(List<Get> gets) throws IOException;
123 
124   /**
125    * Return the row that matches <i>row</i> exactly,
126    * or the one that immediately precedes it.
127    *
128    * @param row A row key.
129    * @param family Column family to include in the {@link Result}.
130    * @throws IOException if a remote or network exception occurs.
131    * @since 0.20.0
132    */
133   Result getRowOrBefore(byte[] row, byte[] family) throws IOException;
134 
135   /**
136    * Returns a scanner on the current table as specified by the {@link Scan}
137    * object.
138    *
139    * @param scan A configured {@link Scan} object.
140    * @return A scanner.
141    * @throws IOException if a remote or network exception occurs.
142    * @since 0.20.0
143    */
144   ResultScanner getScanner(Scan scan) throws IOException;
145 
146   /**
147    * Gets a scanner on the current table for the given family.
148    *
149    * @param family The column family to scan.
150    * @return A scanner.
151    * @throws IOException if a remote or network exception occurs.
152    * @since 0.20.0
153    */
154   ResultScanner getScanner(byte[] family) throws IOException;
155 
156   /**
157    * Gets a scanner on the current table for the given family and qualifier.
158    *
159    * @param family The column family to scan.
160    * @param qualifier The column qualifier to scan.
161    * @return A scanner.
162    * @throws IOException if a remote or network exception occurs.
163    * @since 0.20.0
164    */
165   ResultScanner getScanner(byte[] family, byte[] qualifier) throws IOException;
166 
167 
168   /**
169    * Puts some data in the table.
170    * <p>
171    * If {@link #isAutoFlush isAutoFlush} is false, the update is buffered
172    * until the internal buffer is full.
173    * @param put The data to put.
174    * @throws IOException if a remote or network exception occurs.
175    * @since 0.20.0
176    */
177   void put(Put put) throws IOException;
178 
179   /**
180    * Puts some data in the table, in batch.
181    * <p>
182    * If {@link #isAutoFlush isAutoFlush} is false, the update is buffered
183    * until the internal buffer is full.
184    * @param puts The list of mutations to apply. The batch put is done by
185    * aggregating the iteration of the Puts over the write buffer
186    * at the client-side for a single RPC call.
187    * @throws IOException if a remote or network exception occurs.
188    * @since 0.20.0
189    */
190   void put(List<Put> puts) throws IOException;
191 
192   /**
193    * Atomically checks if a row/family/qualifier value matches the expected
194    * value. If it does, it adds the put.  If the passed value is null, the check
195    * is for the lack of column (ie: non-existance)
196    *
197    * @param row to check
198    * @param family column family to check
199    * @param qualifier column qualifier to check
200    * @param value the expected value
201    * @param put data to put if check succeeds
202    * @throws IOException e
203    * @return true if the new put was executed, false otherwise
204    */
205   boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier,
206       byte[] value, Put put) throws IOException;
207 
208   /**
209    * Deletes the specified cells/row.
210    *
211    * @param delete The object that specifies what to delete.
212    * @throws IOException if a remote or network exception occurs.
213    * @since 0.20.0
214    */
215   void delete(Delete delete) throws IOException;
216 
217   /**
218    * Deletes the specified cells/rows in bulk.
219    * @param deletes List of things to delete.  List gets modified by this
220    * method (in particular it gets re-ordered, so the order in which the elements
221    * are inserted in the list gives no guarantee as to the order in which the
222    * {@link Delete}s are executed).
223    * @throws IOException if a remote or network exception occurs. In that case
224    * the {@code deletes} argument will contain the {@link Delete} instances
225    * that have not be successfully applied.
226    * @since 0.20.1
227    */
228   void delete(List<Delete> deletes) throws IOException;
229 
230   /**
231    * Atomically checks if a row/family/qualifier value matches the expected
232    * value. If it does, it adds the delete.  If the passed value is null, the
233    * check is for the lack of column (ie: non-existance)
234    *
235    * @param row to check
236    * @param family column family to check
237    * @param qualifier column qualifier to check
238    * @param value the expected value
239    * @param delete data to delete if check succeeds
240    * @throws IOException e
241    * @return true if the new delete was executed, false otherwise
242    */
243   boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
244       byte[] value, Delete delete) throws IOException;
245 
246   /**
247    * Increments one or more columns within a single row.
248    * <p>
249    * This operation does not appear atomic to readers.  Increments are done
250    * under a single row lock, so write operations to a row are synchronized, but
251    * readers do not take row locks so get and scan operations can see this
252    * operation partially completed.
253    *
254    * @param increment object that specifies the columns and amounts to be used
255    *                  for the increment operations
256    * @throws IOException e
257    * @return values of columns after the increment
258    */
259   public Result increment(final Increment increment) throws IOException;
260 
261   /**
262    * Atomically increments a column value.
263    * <p>
264    * Equivalent to {@code {@link #incrementColumnValue(byte[], byte[], byte[],
265    * long, boolean) incrementColumnValue}(row, family, qualifier, amount,
266    * <b>true</b>)}
267    * @param row The row that contains the cell to increment.
268    * @param family The column family of the cell to increment.
269    * @param qualifier The column qualifier of the cell to increment.
270    * @param amount The amount to increment the cell with (or decrement, if the
271    * amount is negative).
272    * @return The new value, post increment.
273    * @throws IOException if a remote or network exception occurs.
274    */
275   long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
276       long amount) throws IOException;
277 
278   /**
279    * Atomically increments a column value. If the column value already exists
280    * and is not a big-endian long, this could throw an exception. If the column
281    * value does not yet exist it is initialized to <code>amount</code> and
282    * written to the specified column.
283    *
284    * <p>Setting writeToWAL to false means that in a fail scenario, you will lose
285    * any increments that have not been flushed.
286    * @param row The row that contains the cell to increment.
287    * @param family The column family of the cell to increment.
288    * @param qualifier The column qualifier of the cell to increment.
289    * @param amount The amount to increment the cell with (or decrement, if the
290    * amount is negative).
291    * @param writeToWAL if {@code true}, the operation will be applied to the
292    * Write Ahead Log (WAL).  This makes the operation slower but safer, as if
293    * the call returns successfully, it is guaranteed that the increment will
294    * be safely persisted.  When set to {@code false}, the call may return
295    * successfully before the increment is safely persisted, so it's possible
296    * that the increment be lost in the event of a failure happening before the
297    * operation gets persisted.
298    * @return The new value, post increment.
299    * @throws IOException if a remote or network exception occurs.
300    */
301   long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
302       long amount, boolean writeToWAL) throws IOException;
303 
304   /**
305    * Tells whether or not 'auto-flush' is turned on.
306    *
307    * @return {@code true} if 'auto-flush' is enabled (default), meaning
308    * {@link Put} operations don't get buffered/delayed and are immediately
309    * executed.
310    */
311   boolean isAutoFlush();
312 
313   /**
314    * Executes all the buffered {@link Put} operations.
315    * <p>
316    * This method gets called once automatically for every {@link Put} or batch
317    * of {@link Put}s (when <code>put(List<Put>)</code> is used) when
318    * {@link #isAutoFlush} is {@code true}.
319    * @throws IOException if a remote or network exception occurs.
320    */
321   void flushCommits() throws IOException;
322 
323   /**
324    * Releases any resources help or pending changes in internal buffers.
325    *
326    * @throws IOException if a remote or network exception occurs.
327    */
328   void close() throws IOException;
329 
330   /**
331    * Obtains a lock on a row.
332    *
333    * @param row The row to lock.
334    * @return A {@link RowLock} containing the row and lock id.
335    * @throws IOException if a remote or network exception occurs.
336    * @see RowLock
337    * @see #unlockRow
338    */
339   RowLock lockRow(byte[] row) throws IOException;
340 
341   /**
342    * Releases a row lock.
343    *
344    * @param rl The row lock to release.
345    * @throws IOException if a remote or network exception occurs.
346    * @see RowLock
347    * @see #unlockRow
348    */
349   void unlockRow(RowLock rl) throws IOException;
350 }