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 org.apache.hadoop.conf.Configuration;
23  import org.apache.hadoop.hbase.HTableDescriptor;
24  
25  import java.io.IOException;
26  import java.util.List;
27  
28  /**
29   * Used to communicate with a single HBase table.
30   *
31   * @since 0.21.0
32   */
33  public interface HTableInterface {
34  
35    /**
36     * Gets the name of this table.
37     *
38     * @return the table name.
39     */
40    byte[] getTableName();
41  
42    /**
43     * Returns the {@link Configuration} object used by this instance.
44     * <p>
45     * The reference returned is not a copy, so any change made to it will
46     * affect this instance.
47     */
48    Configuration getConfiguration();
49  
50    /**
51     * Gets the {@link HTableDescriptor table descriptor} for this table.
52     * @throws IOException if a remote or network exception occurs.
53     */
54    HTableDescriptor getTableDescriptor() throws IOException;
55  
56    /**
57     * Test for the existence of columns in the table, as specified in the Get.
58     * <p>
59     *
60     * This will return true if the Get matches one or more keys, false if not.
61     * <p>
62     *
63     * This is a server-side call so it prevents any data from being transfered to
64     * the client.
65     *
66     * @param get the Get
67     * @return true if the specified Get matches one or more keys, false if not
68     * @throws IOException e
69     */
70    boolean exists(Get get) throws IOException;
71  
72    /**
73     * Extracts certain cells from a given row.
74     * @param get The object that specifies what data to fetch and from which row.
75     * @return The data coming from the specified row, if it exists.  If the row
76     * specified doesn't exist, the {@link Result} instance returned won't
77     * contain any {@link KeyValue}, as indicated by {@link Result#isEmpty()}.
78     * @throws IOException if a remote or network exception occurs.
79     * @since 0.20.0
80     */
81    Result get(Get get) throws IOException;
82  
83    /**
84     * Return the row that matches <i>row</i> exactly,
85     * or the one that immediately precedes it.
86     *
87     * @param row A row key.
88     * @param family Column family to include in the {@link Result}.
89     * @throws IOException if a remote or network exception occurs.
90     * @since 0.20.0
91     */
92    Result getRowOrBefore(byte[] row, byte[] family) throws IOException;
93  
94    /**
95     * Returns a scanner on the current table as specified by the {@link Scan}
96     * object.
97     *
98     * @param scan A configured {@link Scan} object.
99     * @return A scanner.
100    * @throws IOException if a remote or network exception occurs.
101    * @since 0.20.0
102    */
103   ResultScanner getScanner(Scan scan) throws IOException;
104 
105   /**
106    * Gets a scanner on the current table for the given family.
107    *
108    * @param family The column family to scan.
109    * @return A scanner.
110    * @throws IOException if a remote or network exception occurs.
111    * @since 0.20.0
112    */
113   ResultScanner getScanner(byte[] family) throws IOException;
114 
115   /**
116    * Gets a scanner on the current table for the given family and qualifier.
117    *
118    * @param family The column family to scan.
119    * @param qualifier The column qualifier to scan.
120    * @return A scanner.
121    * @throws IOException if a remote or network exception occurs.
122    * @since 0.20.0
123    */
124   ResultScanner getScanner(byte[] family, byte[] qualifier) throws IOException;
125 
126 
127   /**
128    * Puts some data in the table.
129    * <p>
130    * If {@link #isAutoFlush isAutoFlush} is false, the update is buffered
131    * until the internal buffer is full.
132    * @param put The data to put.
133    * @throws IOException if a remote or network exception occurs.
134    * @since 0.20.0
135    */
136   void put(Put put) throws IOException;
137 
138   /**
139    * Puts some data in the table, in batch.
140    * <p>
141    * If {@link #isAutoFlush isAutoFlush} is false, the update is buffered
142    * until the internal buffer is full.
143    * @param puts The list of mutations to apply.  The list gets modified by this
144    * method (in particular it gets re-ordered, so the order in which the elements
145    * are inserted in the list gives no guarantee as to the order in which the
146    * {@link Put}s are executed).
147    * @throws IOException if a remote or network exception occurs. In that case
148    * the {@code puts} argument will contain the {@link Put} instances that
149    * have not be successfully applied.
150    * @since 0.20.0
151    */
152   void put(List<Put> puts) throws IOException;
153 
154   /**
155    * Atomically checks if a row/family/qualifier value matches the expected
156    * value. If it does, it adds the put.  If the passed value is null, the check
157    * is for the lack of column (ie: non-existance)
158    *
159    * @param row to check
160    * @param family column family to check
161    * @param qualifier column qualifier to check
162    * @param value the expected value
163    * @param put data to put if check succeeds
164    * @throws IOException e
165    * @return true if the new put was executed, false otherwise
166    */
167   boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier,
168       byte[] value, Put put) throws IOException;
169 
170   /**
171    * Deletes the specified cells/row.
172    *
173    * @param delete The object that specifies what to delete.
174    * @throws IOException if a remote or network exception occurs.
175    * @since 0.20.0
176    */
177   void delete(Delete delete) throws IOException;
178 
179   /**
180    * Deletes the specified cells/rows in bulk.
181    * @param deletes List of things to delete.  List gets modified by this
182    * method (in particular it gets re-ordered, so the order in which the elements
183    * are inserted in the list gives no guarantee as to the order in which the
184    * {@link Delete}s are executed).
185    * @throws IOException if a remote or network exception occurs. In that case
186    * the {@code deletes} argument will contain the {@link Delete} instances
187    * that have not be successfully applied.
188    * @since 0.20.1
189    */
190   void delete(List<Delete> deletes) throws IOException;
191 
192   /**
193    * Atomically checks if a row/family/qualifier value matches the expected
194    * value. If it does, it adds the delete.  If the passed value is null, the 
195    * check 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 delete data to delete if check succeeds
202    * @throws IOException e
203    * @return true if the new delete was executed, false otherwise
204    */
205   boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
206       byte[] value, Delete delete) throws IOException;
207 
208   /**
209    * Atomically increments a column value.
210    * <p>
211    * Equivalent to {@code {@link #incrementColumnValue(byte[], byte[], byte[],
212    * long, boolean) incrementColumnValue}(row, family, qualifier, amount,
213    * <b>true</b>)}
214    * @param row The row that contains the cell to increment.
215    * @param family The column family of the cell to increment.
216    * @param qualifier The column qualifier of the cell to increment.
217    * @param amount The amount to increment the cell with (or decrement, if the
218    * amount is negative).
219    * @return The new value, post increment.
220    * @throws IOException if a remote or network exception occurs.
221    */
222   long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
223       long amount) throws IOException;
224 
225   /**
226    * Atomically increments a column value. If the column value already exists
227    * and is not a big-endian long, this could throw an exception. If the column
228    * value does not yet exist it is initialized to <code>amount</code> and
229    * written to the specified column.
230    *
231    * <p>Setting writeToWAL to false means that in a fail scenario, you will lose
232    * any increments that have not been flushed.
233    * @param row The row that contains the cell to increment.
234    * @param family The column family of the cell to increment.
235    * @param qualifier The column qualifier of the cell to increment.
236    * @param amount The amount to increment the cell with (or decrement, if the
237    * amount is negative).
238    * @param writeToWAL if {@code true}, the operation will be applied to the
239    * Write Ahead Log (WAL).  This makes the operation slower but safer, as if
240    * the call returns successfully, it is guaranteed that the increment will
241    * be safely persisted.  When set to {@code false}, the call may return
242    * successfully before the increment is safely persisted, so it's possible
243    * that the increment be lost in the event of a failure happening before the
244    * operation gets persisted.
245    * @return The new value, post increment.
246    * @throws IOException if a remote or network exception occurs.
247    */
248   long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
249       long amount, boolean writeToWAL) throws IOException;
250 
251   /**
252    * Tells whether or not 'auto-flush' is turned on.
253    *
254    * @return {@code true} if 'auto-flush' is enabled (default), meaning
255    * {@link Put} operations don't get buffered/delayed and are immediately
256    * executed.
257    */
258   boolean isAutoFlush();
259 
260   /**
261    * Executes all the buffered {@link Put} operations.
262    * <p>
263    * This method gets called once automatically for every {@link Put} or batch
264    * of {@link Put}s (when {@link #put(List<Put>)} is used) when
265    * {@link #isAutoFlush} is {@code true}.
266    * @throws IOException if a remote or network exception occurs.
267    */
268   void flushCommits() throws IOException;
269 
270   /**
271    * Releases any resources help or pending changes in internal buffers.
272    *
273    * @throws IOException if a remote or network exception occurs.
274    */
275   void close() throws IOException;
276 
277   /**
278    * Obtains a lock on a row.
279    *
280    * @param row The row to lock.
281    * @return A {@link RowLock} containing the row and lock id.
282    * @throws IOException if a remote or network exception occurs.
283    * @see RowLock
284    * @see #unlockRow
285    */
286   RowLock lockRow(byte[] row) throws IOException;
287 
288   /**
289    * Releases a row lock.
290    *
291    * @param rl The row lock to release.
292    * @throws IOException if a remote or network exception occurs.
293    * @see RowLock
294    * @see #unlockRow
295    */
296   void unlockRow(RowLock rl) throws IOException;
297 }