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.ipc; 21 22 import org.apache.hadoop.hbase.HRegionInfo; 23 import org.apache.hadoop.hbase.HServerInfo; 24 import org.apache.hadoop.hbase.NotServingRegionException; 25 import org.apache.hadoop.hbase.client.Delete; 26 import org.apache.hadoop.hbase.client.Get; 27 import org.apache.hadoop.hbase.client.MultiPut; 28 import org.apache.hadoop.hbase.client.MultiPutResponse; 29 import org.apache.hadoop.hbase.client.Put; 30 import org.apache.hadoop.hbase.client.Result; 31 import org.apache.hadoop.hbase.client.Scan; 32 import org.apache.hadoop.hbase.regionserver.HRegion; 33 import org.apache.hadoop.hbase.regionserver.wal.HLog; 34 35 import java.io.IOException; 36 import java.util.List; 37 38 /** 39 * Clients interact with HRegionServers using a handle to the HRegionInterface. 40 * 41 * <p>NOTE: if you change the interface, you must change the RPC version 42 * number in HBaseRPCProtocolVersion 43 */ 44 public interface HRegionInterface extends HBaseRPCProtocolVersion { 45 /** 46 * Get metainfo about an HRegion 47 * 48 * @param regionName name of the region 49 * @return HRegionInfo object for region 50 * @throws NotServingRegionException e 51 */ 52 public HRegionInfo getRegionInfo(final byte [] regionName) 53 throws NotServingRegionException; 54 55 56 /** 57 * Return all the data for the row that matches <i>row</i> exactly, 58 * or the one that immediately preceeds it. 59 * 60 * @param regionName region name 61 * @param row row key 62 * @param family Column family to look for row in. 63 * @return map of values 64 * @throws IOException e 65 */ 66 public Result getClosestRowBefore(final byte [] regionName, 67 final byte [] row, final byte [] family) 68 throws IOException; 69 70 /** 71 * 72 * @return the regions served by this regionserver 73 */ 74 public HRegion [] getOnlineRegionsAsArray(); 75 76 /** 77 * Perform Get operation. 78 * @param regionName name of region to get from 79 * @param get Get operation 80 * @return Result 81 * @throws IOException e 82 */ 83 public Result get(byte [] regionName, Get get) throws IOException; 84 85 /** 86 * Perform exists operation. 87 * @param regionName name of region to get from 88 * @param get Get operation describing cell to test 89 * @return true if exists 90 * @throws IOException e 91 */ 92 public boolean exists(byte [] regionName, Get get) throws IOException; 93 94 /** 95 * Put data into the specified region 96 * @param regionName region name 97 * @param put the data to be put 98 * @throws IOException e 99 */ 100 public void put(final byte [] regionName, final Put put) 101 throws IOException; 102 103 /** 104 * Put an array of puts into the specified region 105 * 106 * @param regionName region name 107 * @param puts List of puts to execute 108 * @return The number of processed put's. Returns -1 if all Puts 109 * processed successfully. 110 * @throws IOException e 111 */ 112 public int put(final byte[] regionName, final List<Put> puts) 113 throws IOException; 114 115 /** 116 * Deletes all the KeyValues that match those found in the Delete object, 117 * if their ts <= to the Delete. In case of a delete with a specific ts it 118 * only deletes that specific KeyValue. 119 * @param regionName region name 120 * @param delete delete object 121 * @throws IOException e 122 */ 123 public void delete(final byte[] regionName, final Delete delete) 124 throws IOException; 125 126 /** 127 * Put an array of deletes into the specified region 128 * 129 * @param regionName region name 130 * @param deletes delete List to execute 131 * @return The number of processed deletes. Returns -1 if all Deletes 132 * processed successfully. 133 * @throws IOException e 134 */ 135 public int delete(final byte[] regionName, final List<Delete> deletes) 136 throws IOException; 137 138 /** 139 * Atomically checks if a row/family/qualifier value match the expectedValue. 140 * If it does, it adds the put. If passed expected value is null, then the 141 * check is for non-existance of the row/column. 142 * 143 * @param regionName region name 144 * @param row row to check 145 * @param family column family 146 * @param qualifier column qualifier 147 * @param value the expected value 148 * @param put data to put if check succeeds 149 * @throws IOException e 150 * @return true if the new put was execute, false otherwise 151 */ 152 public boolean checkAndPut(final byte[] regionName, final byte [] row, 153 final byte [] family, final byte [] qualifier, final byte [] value, 154 final Put put) 155 throws IOException; 156 157 158 /** 159 * Atomically checks if a row/family/qualifier value match the expectedValue. 160 * If it does, it adds the delete. If passed expected value is null, then the 161 * check is for non-existance of the row/column. 162 * 163 * @param regionName region name 164 * @param row row to check 165 * @param family column family 166 * @param qualifier column qualifier 167 * @param value the expected value 168 * @param delete data to delete if check succeeds 169 * @throws IOException e 170 * @return true if the new delete was execute, false otherwise 171 */ 172 public boolean checkAndDelete(final byte[] regionName, final byte [] row, 173 final byte [] family, final byte [] qualifier, final byte [] value, 174 final Delete delete) 175 throws IOException; 176 177 /** 178 * Atomically increments a column value. If the column value isn't long-like, 179 * this could throw an exception. If passed expected value is null, then the 180 * check is for non-existance of the row/column. 181 * 182 * @param regionName region name 183 * @param row row to check 184 * @param family column family 185 * @param qualifier column qualifier 186 * @param amount long amount to increment 187 * @param writeToWAL whether to write the increment to the WAL 188 * @return new incremented column value 189 * @throws IOException e 190 */ 191 public long incrementColumnValue(byte [] regionName, byte [] row, 192 byte [] family, byte [] qualifier, long amount, boolean writeToWAL) 193 throws IOException; 194 195 196 // 197 // remote scanner interface 198 // 199 200 /** 201 * Opens a remote scanner with a RowFilter. 202 * 203 * @param regionName name of region to scan 204 * @param scan configured scan object 205 * @return scannerId scanner identifier used in other calls 206 * @throws IOException e 207 */ 208 public long openScanner(final byte [] regionName, final Scan scan) 209 throws IOException; 210 211 /** 212 * Get the next set of values 213 * @param scannerId clientId passed to openScanner 214 * @return map of values; returns null if no results. 215 * @throws IOException e 216 */ 217 public Result next(long scannerId) throws IOException; 218 219 /** 220 * Get the next set of values 221 * @param scannerId clientId passed to openScanner 222 * @param numberOfRows the number of rows to fetch 223 * @return Array of Results (map of values); array is empty if done with this 224 * region and null if we are NOT to go to the next region (happens when a 225 * filter rules that the scan is done). 226 * @throws IOException e 227 */ 228 public Result [] next(long scannerId, int numberOfRows) throws IOException; 229 230 /** 231 * Close a scanner 232 * 233 * @param scannerId the scanner id returned by openScanner 234 * @throws IOException e 235 */ 236 public void close(long scannerId) throws IOException; 237 238 /** 239 * Opens a remote row lock. 240 * 241 * @param regionName name of region 242 * @param row row to lock 243 * @return lockId lock identifier 244 * @throws IOException e 245 */ 246 public long lockRow(final byte [] regionName, final byte [] row) 247 throws IOException; 248 249 /** 250 * Releases a remote row lock. 251 * 252 * @param regionName region name 253 * @param lockId the lock id returned by lockRow 254 * @throws IOException e 255 */ 256 public void unlockRow(final byte [] regionName, final long lockId) 257 throws IOException; 258 259 260 /** 261 * Method used when a master is taking the place of another failed one. 262 * @return All regions assigned on this region server 263 * @throws IOException e 264 */ 265 public HRegionInfo[] getRegionsAssignment() throws IOException; 266 267 /** 268 * Method used when a master is taking the place of another failed one. 269 * @return The HSI 270 * @throws IOException e 271 */ 272 public HServerInfo getHServerInfo() throws IOException; 273 274 275 /** 276 * Multi put for putting multiple regions worth of puts at once. 277 * 278 * @param puts the request 279 * @return the reply 280 * @throws IOException e 281 */ 282 public MultiPutResponse multiPut(MultiPut puts) throws IOException; 283 284 /** 285 * Bulk load an HFile into an open region 286 */ 287 public void bulkLoadHFile(String hfilePath, 288 byte[] regionName, byte[] familyName) throws IOException; 289 290 /** 291 * Replicates the given entries. The guarantee is that the given entries 292 * will be durable on the slave cluster if this method returns without 293 * any exception. 294 * hbase.replication has to be set to true for this to work. 295 * 296 * @param entries entries to replicate 297 * @throws IOException 298 */ 299 public void replicateLogEntries(HLog.Entry[] entries) throws IOException; 300 301 }