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 list gets modified by this
185    * method (in particular it gets re-ordered, so the order in which the elements
186    * are inserted in the list gives no guarantee as to the order in which the
187    * {@link Put}s are executed).
188    * @throws IOException if a remote or network exception occurs. In that case
189    * the {@code puts} argument will contain the {@link Put} instances that
190    * have not be successfully applied.
191    * @since 0.20.0
192    */
193   void put(List<Put> puts) throws IOException;
194 
195   /**
196    * Atomically checks if a row/family/qualifier value matches the expected
197    * value. If it does, it adds the put.  If the passed value is null, the check
198    * is for the lack of column (ie: non-existance)
199    *
200    * @param row to check
201    * @param family column family to check
202    * @param qualifier column qualifier to check
203    * @param value the expected value
204    * @param put data to put if check succeeds
205    * @throws IOException e
206    * @return true if the new put was executed, false otherwise
207    */
208   boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier,
209       byte[] value, Put put) throws IOException;
210 
211   /**
212    * Deletes the specified cells/row.
213    *
214    * @param delete The object that specifies what to delete.
215    * @throws IOException if a remote or network exception occurs.
216    * @since 0.20.0
217    */
218   void delete(Delete delete) throws IOException;
219 
220   /**
221    * Deletes the specified cells/rows in bulk.
222    * @param deletes List of things to delete.  List gets modified by this
223    * method (in particular it gets re-ordered, so the order in which the elements
224    * are inserted in the list gives no guarantee as to the order in which the
225    * {@link Delete}s are executed).
226    * @throws IOException if a remote or network exception occurs. In that case
227    * the {@code deletes} argument will contain the {@link Delete} instances
228    * that have not be successfully applied.
229    * @since 0.20.1
230    */
231   void delete(List<Delete> deletes) throws IOException;
232 
233   /**
234    * Atomically checks if a row/family/qualifier value matches the expected
235    * value. If it does, it adds the delete.  If the passed value is null, the
236    * check is for the lack of column (ie: non-existance)
237    *
238    * @param row to check
239    * @param family column family to check
240    * @param qualifier column qualifier to check
241    * @param value the expected value
242    * @param delete data to delete if check succeeds
243    * @throws IOException e
244    * @return true if the new delete was executed, false otherwise
245    */
246   boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
247       byte[] value, Delete delete) throws IOException;
248 
249   /**
250    * Increments one or more columns within a single row.
251    * <p>
252    * This operation does not appear atomic to readers.  Increments are done
253    * under a single row lock, so write operations to a row are synchronized, but
254    * readers do not take row locks so get and scan operations can see this
255    * operation partially completed.
256    *
257    * @param increment object that specifies the columns and amounts to be used
258    *                  for the increment operations
259    * @throws IOException e
260    * @return values of columns after the increment
261    */
262   public Result increment(final Increment increment) throws IOException;
263 
264   /**
265    * Atomically increments a column value.
266    * <p>
267    * Equivalent to {@code {@link #incrementColumnValue(byte[], byte[], byte[],
268    * long, boolean) incrementColumnValue}(row, family, qualifier, amount,
269    * <b>true</b>)}
270    * @param row The row that contains the cell to increment.
271    * @param family The column family of the cell to increment.
272    * @param qualifier The column qualifier of the cell to increment.
273    * @param amount The amount to increment the cell with (or decrement, if the
274    * amount is negative).
275    * @return The new value, post increment.
276    * @throws IOException if a remote or network exception occurs.
277    */
278   long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
279       long amount) throws IOException;
280 
281   /**
282    * Atomically increments a column value. If the column value already exists
283    * and is not a big-endian long, this could throw an exception. If the column
284    * value does not yet exist it is initialized to <code>amount</code> and
285    * written to the specified column.
286    *
287    * <p>Setting writeToWAL to false means that in a fail scenario, you will lose
288    * any increments that have not been flushed.
289    * @param row The row that contains the cell to increment.
290    * @param family The column family of the cell to increment.
291    * @param qualifier The column qualifier of the cell to increment.
292    * @param amount The amount to increment the cell with (or decrement, if the
293    * amount is negative).
294    * @param writeToWAL if {@code true}, the operation will be applied to the
295    * Write Ahead Log (WAL).  This makes the operation slower but safer, as if
296    * the call returns successfully, it is guaranteed that the increment will
297    * be safely persisted.  When set to {@code false}, the call may return
298    * successfully before the increment is safely persisted, so it's possible
299    * that the increment be lost in the event of a failure happening before the
300    * operation gets persisted.
301    * @return The new value, post increment.
302    * @throws IOException if a remote or network exception occurs.
303    */
304   long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
305       long amount, boolean writeToWAL) throws IOException;
306 
307   /**
308    * Tells whether or not 'auto-flush' is turned on.
309    *
310    * @return {@code true} if 'auto-flush' is enabled (default), meaning
311    * {@link Put} operations don't get buffered/delayed and are immediately
312    * executed.
313    */
314   boolean isAutoFlush();
315 
316   /**
317    * Executes all the buffered {@link Put} operations.
318    * <p>
319    * This method gets called once automatically for every {@link Put} or batch
320    * of {@link Put}s (when <code>put(List<Put>)</code> is used) when
321    * {@link #isAutoFlush} is {@code true}.
322    * @throws IOException if a remote or network exception occurs.
323    */
324   void flushCommits() throws IOException;
325 
326   /**
327    * Releases any resources help or pending changes in internal buffers.
328    *
329    * @throws IOException if a remote or network exception occurs.
330    */
331   void close() throws IOException;
332 
333   /**
334    * Obtains a lock on a row.
335    *
336    * @param row The row to lock.
337    * @return A {@link RowLock} containing the row and lock id.
338    * @throws IOException if a remote or network exception occurs.
339    * @see RowLock
340    * @see #unlockRow
341    */
342   RowLock lockRow(byte[] row) throws IOException;
343 
344   /**
345    * Releases a row lock.
346    *
347    * @param rl The row lock to release.
348    * @throws IOException if a remote or network exception occurs.
349    * @see RowLock
350    * @see #unlockRow
351    */
352   void unlockRow(RowLock rl) throws IOException;
353 }