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 }