1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.apache.hadoop.hbase.client;
19
20 import java.io.IOException;
21 import java.io.InterruptedIOException;
22 import java.util.ArrayList;
23 import java.util.Arrays;
24 import java.util.LinkedList;
25 import java.util.List;
26 import java.util.concurrent.ExecutorService;
27
28 import org.apache.commons.logging.Log;
29 import org.apache.commons.logging.LogFactory;
30 import org.apache.hadoop.hbase.KeyValue.MetaComparator;
31 import org.apache.hadoop.hbase.classification.InterfaceAudience;
32 import org.apache.hadoop.conf.Configuration;
33 import org.apache.hadoop.hbase.Cell;
34 import org.apache.hadoop.hbase.CellComparator;
35 import org.apache.hadoop.hbase.CellUtil;
36 import org.apache.hadoop.hbase.DoNotRetryIOException;
37 import org.apache.hadoop.hbase.HBaseConfiguration;
38 import org.apache.hadoop.hbase.HConstants;
39 import org.apache.hadoop.hbase.HRegionInfo;
40 import org.apache.hadoop.hbase.NotServingRegionException;
41 import org.apache.hadoop.hbase.TableName;
42 import org.apache.hadoop.hbase.UnknownScannerException;
43 import org.apache.hadoop.hbase.exceptions.OutOfOrderScannerNextException;
44 import org.apache.hadoop.hbase.exceptions.ScannerResetException;
45 import org.apache.hadoop.hbase.ipc.RpcControllerFactory;
46 import org.apache.hadoop.hbase.protobuf.ProtobufUtil;
47 import org.apache.hadoop.hbase.protobuf.generated.MapReduceProtos;
48 import org.apache.hadoop.hbase.regionserver.RegionServerStoppedException;
49 import org.apache.hadoop.hbase.util.Bytes;
50
51 import com.google.common.annotations.VisibleForTesting;
52
53 /**
54 * Implements the scanner interface for the HBase client.
55 * If there are multiple regions in a table, this scanner will iterate
56 * through them all.
57 */
58 @InterfaceAudience.Private
59 public class ClientScanner extends AbstractClientScanner {
60 private final Log LOG = LogFactory.getLog(this.getClass());
61 // A byte array in which all elements are the max byte, and it is used to
62 // construct closest front row
63 static byte[] MAX_BYTE_ARRAY = Bytes.createMaxByteArray(9);
64 protected Scan scan;
65 protected boolean closed = false;
66 // Current region scanner is against. Gets cleared if current region goes
67 // wonky: e.g. if it splits on us.
68 protected HRegionInfo currentRegion = null;
69 protected ScannerCallableWithReplicas callable = null;
70 protected final LinkedList<Result> cache = new LinkedList<Result>();
71 /**
72 * A list of partial results that have been returned from the server. This list should only
73 * contain results if this scanner does not have enough partial results to form the complete
74 * result.
75 */
76 protected final LinkedList<Result> partialResults = new LinkedList<Result>();
77 /**
78 * The row for which we are accumulating partial Results (i.e. the row of the Results stored
79 * inside partialResults). Changes to partialResultsRow and partialResults are kept in sync
80 * via the methods {@link #addToPartialResults(Result)} and {@link #clearPartialResults()}
81 */
82 protected byte[] partialResultsRow = null;
83 /**
84 * The last cell from a not full Row which is added to cache
85 */
86 protected Cell lastCellLoadedToCache = null;
87 protected final int caching;
88 protected long lastNext;
89 // Keep lastResult returned successfully in case we have to reset scanner.
90 protected Result lastResult = null;
91 protected final long maxScannerResultSize;
92 private final ClusterConnection connection;
93 private final TableName tableName;
94 protected final int scannerTimeout;
95 protected boolean scanMetricsPublished = false;
96 protected RpcRetryingCaller<Result []> caller;
97 protected RpcControllerFactory rpcControllerFactory;
98 protected Configuration conf;
99 //The timeout on the primary. Applicable if there are multiple replicas for a region
100 //In that case, we will only wait for this much timeout on the primary before going
101 //to the replicas and trying the same scan. Note that the retries will still happen
102 //on each replica and the first successful results will be taken. A timeout of 0 is
103 //disallowed.
104 protected final int primaryOperationTimeout;
105 private int retries;
106 protected final ExecutorService pool;
107 private static MetaComparator metaComparator = new MetaComparator();
108
109 /**
110 * Create a new ClientScanner for the specified table Note that the passed {@link Scan}'s start
111 * row maybe changed changed.
112 * @param conf The {@link Configuration} to use.
113 * @param scan {@link Scan} to use in this scanner
114 * @param tableName The table that we wish to scan
115 * @param connection Connection identifying the cluster
116 * @throws IOException
117 */
118 public ClientScanner(final Configuration conf, final Scan scan, final TableName tableName,
119 ClusterConnection connection, RpcRetryingCallerFactory rpcFactory,
120 RpcControllerFactory controllerFactory, ExecutorService pool, int primaryOperationTimeout)
121 throws IOException {
122 if (LOG.isTraceEnabled()) {
123 LOG.trace("Scan table=" + tableName
124 + ", startRow=" + Bytes.toStringBinary(scan.getStartRow()));
125 }
126 this.scan = scan;
127 this.tableName = tableName;
128 this.lastNext = System.currentTimeMillis();
129 this.connection = connection;
130 this.pool = pool;
131 this.primaryOperationTimeout = primaryOperationTimeout;
132 this.retries = conf.getInt(HConstants.HBASE_CLIENT_RETRIES_NUMBER,
133 HConstants.DEFAULT_HBASE_CLIENT_RETRIES_NUMBER);
134 if (scan.getMaxResultSize() > 0) {
135 this.maxScannerResultSize = scan.getMaxResultSize();
136 } else {
137 this.maxScannerResultSize = conf.getLong(
138 HConstants.HBASE_CLIENT_SCANNER_MAX_RESULT_SIZE_KEY,
139 HConstants.DEFAULT_HBASE_CLIENT_SCANNER_MAX_RESULT_SIZE);
140 }
141 this.scannerTimeout = HBaseConfiguration.getInt(conf,
142 HConstants.HBASE_CLIENT_SCANNER_TIMEOUT_PERIOD,
143 HConstants.HBASE_REGIONSERVER_LEASE_PERIOD_KEY,
144 HConstants.DEFAULT_HBASE_CLIENT_SCANNER_TIMEOUT_PERIOD);
145
146 // check if application wants to collect scan metrics
147 initScanMetrics(scan);
148
149 // Use the caching from the Scan. If not set, use the default cache setting for this table.
150 if (this.scan.getCaching() > 0) {
151 this.caching = this.scan.getCaching();
152 } else {
153 this.caching = conf.getInt(
154 HConstants.HBASE_CLIENT_SCANNER_CACHING,
155 HConstants.DEFAULT_HBASE_CLIENT_SCANNER_CACHING);
156 }
157
158 this.caller = rpcFactory.<Result[]> newCaller();
159 this.rpcControllerFactory = controllerFactory;
160
161 this.conf = conf;
162 initializeScannerInConstruction();
163 }
164
165 protected void initializeScannerInConstruction() throws IOException{
166 // initialize the scanner
167 nextScanner(this.caching, false);
168 }
169
170 protected ClusterConnection getConnection() {
171 return this.connection;
172 }
173
174 /**
175 * @return Table name
176 * @deprecated As of release 0.96
177 * (<a href="https://issues.apache.org/jira/browse/HBASE-9508">HBASE-9508</a>).
178 * This will be removed in HBase 2.0.0. Use {@link #getTable()}.
179 */
180 @Deprecated
181 protected byte [] getTableName() {
182 return this.tableName.getName();
183 }
184
185 protected TableName getTable() {
186 return this.tableName;
187 }
188
189 protected int getRetries() {
190 return this.retries;
191 }
192
193 protected int getScannerTimeout() {
194 return this.scannerTimeout;
195 }
196
197 protected Configuration getConf() {
198 return this.conf;
199 }
200
201 protected Scan getScan() {
202 return scan;
203 }
204
205 protected ExecutorService getPool() {
206 return pool;
207 }
208
209 protected int getPrimaryOperationTimeout() {
210 return primaryOperationTimeout;
211 }
212
213 protected int getCaching() {
214 return caching;
215 }
216
217 protected long getTimestamp() {
218 return lastNext;
219 }
220
221 @VisibleForTesting
222 protected long getMaxResultSize() {
223 return maxScannerResultSize;
224 }
225
226 // returns true if the passed region endKey
227 protected boolean checkScanStopRow(final byte [] endKey) {
228 if (this.scan.getStopRow().length > 0) {
229 // there is a stop row, check to see if we are past it.
230 byte [] stopRow = scan.getStopRow();
231 int cmp = Bytes.compareTo(stopRow, 0, stopRow.length,
232 endKey, 0, endKey.length);
233 if (cmp <= 0) {
234 // stopRow <= endKey (endKey is equals to or larger than stopRow)
235 // This is a stop.
236 return true;
237 }
238 }
239 return false; //unlikely.
240 }
241
242 private boolean possiblyNextScanner(int nbRows, final boolean done) throws IOException {
243 // If we have just switched replica, don't go to the next scanner yet. Rather, try
244 // the scanner operations on the new replica, from the right point in the scan
245 // Note that when we switched to a different replica we left it at a point
246 // where we just did the "openScanner" with the appropriate startrow
247 if (callable != null && callable.switchedToADifferentReplica()) return true;
248 return nextScanner(nbRows, done);
249 }
250
251 /*
252 * Gets a scanner for the next region. If this.currentRegion != null, then
253 * we will move to the endrow of this.currentRegion. Else we will get
254 * scanner at the scan.getStartRow(). We will go no further, just tidy
255 * up outstanding scanners, if <code>currentRegion != null</code> and
256 * <code>done</code> is true.
257 * @param nbRows
258 * @param done Server-side says we're done scanning.
259 */
260 protected boolean nextScanner(int nbRows, final boolean done)
261 throws IOException {
262 // Close the previous scanner if it's open
263 if (this.callable != null) {
264 this.callable.setClose();
265 call(callable, caller, scannerTimeout);
266 this.callable = null;
267 }
268
269 // Where to start the next scanner
270 byte [] localStartKey;
271
272 // if we're at end of table, close and return false to stop iterating
273 if (this.currentRegion != null) {
274 byte [] endKey = this.currentRegion.getEndKey();
275 if (endKey == null ||
276 Bytes.equals(endKey, HConstants.EMPTY_BYTE_ARRAY) ||
277 checkScanStopRow(endKey) ||
278 done) {
279 close();
280 if (LOG.isTraceEnabled()) {
281 LOG.trace("Finished " + this.currentRegion);
282 }
283 return false;
284 }
285 localStartKey = endKey;
286 if (LOG.isTraceEnabled()) {
287 LOG.trace("Finished " + this.currentRegion);
288 }
289 } else {
290 localStartKey = this.scan.getStartRow();
291 }
292
293 if (LOG.isDebugEnabled() && this.currentRegion != null) {
294 // Only worth logging if NOT first region in scan.
295 LOG.debug("Advancing internal scanner to startKey at '" +
296 Bytes.toStringBinary(localStartKey) + "'");
297 }
298 try {
299 callable = getScannerCallable(localStartKey, nbRows);
300 // Open a scanner on the region server starting at the
301 // beginning of the region
302 call(callable, caller, scannerTimeout);
303 this.currentRegion = callable.getHRegionInfo();
304 if (this.scanMetrics != null) {
305 this.scanMetrics.countOfRegions.incrementAndGet();
306 }
307 } catch (IOException e) {
308 close();
309 throw e;
310 }
311 return true;
312 }
313
314 @VisibleForTesting
315 boolean isAnyRPCcancelled() {
316 return callable.isAnyRPCcancelled();
317 }
318
319 Result[] call(ScannerCallableWithReplicas callable,
320 RpcRetryingCaller<Result[]> caller, int scannerTimeout)
321 throws IOException, RuntimeException {
322 if (Thread.interrupted()) {
323 throw new InterruptedIOException();
324 }
325 // callWithoutRetries is at this layer. Within the ScannerCallableWithReplicas,
326 // we do a callWithRetries
327 return caller.callWithoutRetries(callable, scannerTimeout);
328 }
329
330 @InterfaceAudience.Private
331 protected ScannerCallableWithReplicas getScannerCallable(byte [] localStartKey,
332 int nbRows) {
333 scan.setStartRow(localStartKey);
334 ScannerCallable s =
335 new ScannerCallable(getConnection(), getTable(), scan, this.scanMetrics,
336 this.rpcControllerFactory);
337 s.setCaching(nbRows);
338 ScannerCallableWithReplicas sr = new ScannerCallableWithReplicas(tableName, getConnection(),
339 s, pool, primaryOperationTimeout, scan,
340 retries, scannerTimeout, caching, conf, caller);
341 return sr;
342 }
343
344 /**
345 * Publish the scan metrics. For now, we use scan.setAttribute to pass the metrics back to the
346 * application or TableInputFormat.Later, we could push it to other systems. We don't use
347 * metrics framework because it doesn't support multi-instances of the same metrics on the same
348 * machine; for scan/map reduce scenarios, we will have multiple scans running at the same time.
349 *
350 * By default, scan metrics are disabled; if the application wants to collect them, this
351 * behavior can be turned on by calling calling {@link Scan#setScanMetricsEnabled(boolean)}
352 *
353 * <p>This invocation clears the scan metrics. Metrics are aggregated in the Scan instance.
354 */
355 protected void writeScanMetrics() {
356 if (this.scanMetrics == null || scanMetricsPublished) {
357 return;
358 }
359 MapReduceProtos.ScanMetrics pScanMetrics = ProtobufUtil.toScanMetrics(scanMetrics);
360 scan.setAttribute(Scan.SCAN_ATTRIBUTES_METRICS_DATA, pScanMetrics.toByteArray());
361 scanMetricsPublished = true;
362 }
363
364 @Override
365 public Result next() throws IOException {
366 // If the scanner is closed and there's nothing left in the cache, next is a no-op.
367 if (cache.size() == 0 && this.closed) {
368 return null;
369 }
370 if (cache.size() == 0) {
371 loadCache();
372 }
373
374 if (cache.size() > 0) {
375 return cache.poll();
376 }
377
378 // if we exhausted this scanner before calling close, write out the scan metrics
379 writeScanMetrics();
380 return null;
381 }
382
383 @VisibleForTesting
384 public int getCacheSize() {
385 return cache != null ? cache.size() : 0;
386 }
387
388 /**
389 * Contact the servers to load more {@link Result}s in the cache.
390 */
391 protected void loadCache() throws IOException {
392 Result[] values = null;
393 long remainingResultSize = maxScannerResultSize;
394 int countdown = this.caching;
395 // We need to reset it if it's a new callable that was created with a countdown in nextScanner
396 callable.setCaching(this.caching);
397 // This flag is set when we want to skip the result returned. We do
398 // this when we reset scanner because it split under us.
399 boolean retryAfterOutOfOrderException = true;
400 // We don't expect that the server will have more results for us if
401 // it doesn't tell us otherwise. We rely on the size or count of results
402 boolean serverHasMoreResults = false;
403 boolean allResultsSkipped = false;
404 // Even if we are retrying due to UnknownScannerException, ScannerResetException, etc. we should
405 // make sure that we are not retrying indefinitely.
406 int retriesLeft = getRetries();
407 do {
408 allResultsSkipped = false;
409 try {
410 // Server returns a null values if scanning is to stop. Else,
411 // returns an empty array if scanning is to go on and we've just
412 // exhausted current region.
413 values = call(callable, caller, scannerTimeout);
414 // When the replica switch happens, we need to do certain operations again.
415 // The callable will openScanner with the right startkey but we need to pick up
416 // from there. Bypass the rest of the loop and let the catch-up happen in the beginning
417 // of the loop as it happens for the cases where we see exceptions.
418 // Since only openScanner would have happened, values would be null
419 if (values == null && callable.switchedToADifferentReplica()) {
420 // Any accumulated partial results are no longer valid since the callable will
421 // openScanner with the correct startkey and we must pick up from there
422 clearPartialResults();
423 this.currentRegion = callable.getHRegionInfo();
424 continue;
425 }
426 retryAfterOutOfOrderException = true;
427 } catch (DoNotRetryIOException e) {
428 // An exception was thrown which makes any partial results that we were collecting
429 // invalid. The scanner will need to be reset to the beginning of a row.
430 clearPartialResults();
431
432 // Unfortunately, DNRIOE is used in two different semantics.
433 // (1) The first is to close the client scanner and bubble up the exception all the way
434 // to the application. This is preferred when the exception is really un-recoverable
435 // (like CorruptHFileException, etc). Plain DoNotRetryIOException also falls into this
436 // bucket usually.
437 // (2) Second semantics is to close the current region scanner only, but continue the
438 // client scanner by overriding the exception. This is usually UnknownScannerException,
439 // OutOfOrderScannerNextException, etc where the region scanner has to be closed, but the
440 // application-level ClientScanner has to continue without bubbling up the exception to
441 // the client. See RSRpcServices to see how it throws DNRIOE's.
442 // See also: HBASE-16604, HBASE-17187
443
444 if (e instanceof UnknownScannerException) {
445 long timeout = lastNext + scannerTimeout;
446 // If we are over the timeout, throw this exception to the client wrapped in
447 // a ScannerTimeoutException. Else, it's because the region moved and we used the old
448 // id against the new region server; reset the scanner.
449 if (timeout < System.currentTimeMillis()) {
450 LOG.info("For hints related to the following exception, please try taking a look at: "
451 + "https://hbase.apache.org/book.html#trouble.client.scantimeout");
452 long elapsed = System.currentTimeMillis() - lastNext;
453 ScannerTimeoutException ex =
454 new ScannerTimeoutException(elapsed + "ms passed since the last invocation, "
455 + "timeout is currently set to " + scannerTimeout);
456 ex.initCause(e);
457 throw ex;
458 }
459 if (retriesLeft-- <= 0) {
460 throw e; // no more retries
461 }
462 } else {
463 // If exception is any but the list below throw it back to the client; else setup
464 // the scanner and retry.
465 Throwable cause = e.getCause();
466 if ((cause != null && cause instanceof NotServingRegionException) ||
467 (cause != null && cause instanceof RegionServerStoppedException) ||
468 e instanceof OutOfOrderScannerNextException ||
469 e instanceof ScannerResetException) {
470 // Pass. It is easier writing the if loop test as list of what is allowed rather than
471 // as a list of what is not allowed... so if in here, it means we do not throw.
472 if (retriesLeft-- <= 0) {
473 throw e; // no more retries
474 }
475 } else {
476 throw e;
477 }
478 }
479 // Else, its signal from depths of ScannerCallable that we need to reset the scanner.
480 if (this.lastResult != null) {
481 // The region has moved. We need to open a brand new scanner at the new location.
482 // Reset the startRow to the row we've seen last so that the new scanner starts at
483 // the correct row. Otherwise we may see previously returned rows again.
484 // (ScannerCallable by now has "relocated" the correct region)
485 if (!this.lastResult.isPartial() && scan.getBatch() < 0 ) {
486 if (scan.isReversed()) {
487 scan.setStartRow(createClosestRowBefore(lastResult.getRow()));
488 } else {
489 scan.setStartRow(Bytes.add(lastResult.getRow(), new byte[1]));
490 }
491 } else {
492 // we need rescan this row because we only loaded partial row before
493 scan.setStartRow(lastResult.getRow());
494 }
495 }
496 if (e instanceof OutOfOrderScannerNextException) {
497 if (retryAfterOutOfOrderException) {
498 retryAfterOutOfOrderException = false;
499 } else {
500 // TODO: Why wrap this in a DNRIOE when it already is a DNRIOE?
501 throw new DoNotRetryIOException("Failed after retry of " +
502 "OutOfOrderScannerNextException: was there a rpc timeout?", e);
503 }
504 }
505 // Clear region.
506 this.currentRegion = null;
507 // Set this to zero so we don't try and do an rpc and close on remote server when
508 // the exception we got was UnknownScanner or the Server is going down.
509 callable = null;
510 // This continue will take us to while at end of loop where we will set up new scanner.
511 continue;
512 }
513 long currentTime = System.currentTimeMillis();
514 if (this.scanMetrics != null) {
515 this.scanMetrics.sumOfMillisSecBetweenNexts.addAndGet(currentTime - lastNext);
516 }
517 lastNext = currentTime;
518 // Groom the array of Results that we received back from the server before adding that
519 // Results to the scanner's cache. If partial results are not allowed to be seen by the
520 // caller, all book keeping will be performed within this method.
521 List<Result> resultsToAddToCache =
522 getResultsToAddToCache(values, callable.isHeartbeatMessage());
523 if (!resultsToAddToCache.isEmpty()) {
524 for (Result rs : resultsToAddToCache) {
525 rs = filterLoadedCell(rs);
526 if (rs == null) {
527 continue;
528 }
529 cache.add(rs);
530 for (Cell cell : rs.rawCells()) {
531 remainingResultSize -= CellUtil.estimatedHeapSizeOf(cell);
532 }
533 countdown--;
534 this.lastResult = rs;
535 if (this.lastResult.isPartial() || scan.getBatch() > 0 ) {
536 updateLastCellLoadedToCache(this.lastResult);
537 } else {
538 this.lastCellLoadedToCache = null;
539 }
540 }
541 if (cache.isEmpty()) {
542 // all result has been seen before, we need scan more.
543 allResultsSkipped = true;
544 continue;
545 }
546 }
547 if (callable.isHeartbeatMessage()) {
548 if (cache.size() > 0) {
549 // Caller of this method just wants a Result. If we see a heartbeat message, it means
550 // processing of the scan is taking a long time server side. Rather than continue to
551 // loop until a limit (e.g. size or caching) is reached, break out early to avoid causing
552 // unnecesary delays to the caller
553 if (LOG.isTraceEnabled()) {
554 LOG.trace("Heartbeat message received and cache contains Results."
555 + " Breaking out of scan loop");
556 }
557 break;
558 }
559 continue;
560 }
561
562 // We expect that the server won't have more results for us when we exhaust
563 // the size (bytes or count) of the results returned. If the server *does* inform us that
564 // there are more results, we want to avoid possiblyNextScanner(...). Only when we actually
565 // get results is the moreResults context valid.
566 if (null != values && values.length > 0 && callable.hasMoreResultsContext()) {
567 // Only adhere to more server results when we don't have any partialResults
568 // as it keeps the outer loop logic the same.
569 serverHasMoreResults = callable.getServerHasMoreResults() && partialResults.isEmpty();
570 }
571 // Values == null means server-side filter has determined we must STOP
572 // !partialResults.isEmpty() means that we are still accumulating partial Results for a
573 // row. We should not change scanners before we receive all the partial Results for that
574 // row.
575 } while (allResultsSkipped || (callable != null && callable.isHeartbeatMessage())
576 || (doneWithRegion(remainingResultSize, countdown, serverHasMoreResults)
577 && (!partialResults.isEmpty() || possiblyNextScanner(countdown, values == null))));
578 }
579
580 /**
581 * @param remainingResultSize
582 * @param remainingRows
583 * @param regionHasMoreResults
584 * @return true when the current region has been exhausted. When the current region has been
585 * exhausted, the region must be changed before scanning can continue
586 */
587 private boolean doneWithRegion(long remainingResultSize, int remainingRows,
588 boolean regionHasMoreResults) {
589 return remainingResultSize > 0 && remainingRows > 0 && !regionHasMoreResults;
590 }
591
592 /**
593 * This method ensures all of our book keeping regarding partial results is kept up to date. This
594 * method should be called once we know that the results we received back from the RPC request do
595 * not contain errors. We return a list of results that should be added to the cache. In general,
596 * this list will contain all NON-partial results from the input array (unless the client has
597 * specified that they are okay with receiving partial results)
598 * @param resultsFromServer The array of {@link Result}s returned from the server
599 * @param heartbeatMessage Flag indicating whether or not the response received from the server
600 * represented a complete response, or a heartbeat message that was sent to keep the
601 * client-server connection alive
602 * @return the list of results that should be added to the cache.
603 * @throws IOException
604 */
605 protected List<Result>
606 getResultsToAddToCache(Result[] resultsFromServer, boolean heartbeatMessage)
607 throws IOException {
608 int resultSize = resultsFromServer != null ? resultsFromServer.length : 0;
609 List<Result> resultsToAddToCache = new ArrayList<Result>(resultSize);
610
611 final boolean isBatchSet = scan != null && scan.getBatch() > 0;
612 final boolean allowPartials = scan != null && scan.getAllowPartialResults();
613
614 // If the caller has indicated in their scan that they are okay with seeing partial results,
615 // then simply add all results to the list. Note that since scan batching also returns results
616 // for a row in pieces we treat batch being set as equivalent to allowing partials. The
617 // implication of treating batching as equivalent to partial results is that it is possible
618 // the caller will receive a result back where the number of cells in the result is less than
619 // the batch size even though it may not be the last group of cells for that row.
620 if (allowPartials || isBatchSet) {
621 addResultsToList(resultsToAddToCache, resultsFromServer, 0,
622 (null == resultsFromServer ? 0 : resultsFromServer.length));
623 return resultsToAddToCache;
624 }
625
626 // If no results were returned it indicates that either we have the all the partial results
627 // necessary to construct the complete result or the server had to send a heartbeat message
628 // to the client to keep the client-server connection alive
629 if (resultsFromServer == null || resultsFromServer.length == 0) {
630 // If this response was an empty heartbeat message, then we have not exhausted the region
631 // and thus there may be more partials server side that still need to be added to the partial
632 // list before we form the complete Result
633 if (!partialResults.isEmpty() && !heartbeatMessage) {
634 resultsToAddToCache.add(Result.createCompleteResult(partialResults));
635 clearPartialResults();
636 }
637
638 return resultsToAddToCache;
639 }
640
641 // In every RPC response there should be at most a single partial result. Furthermore, if
642 // there is a partial result, it is guaranteed to be in the last position of the array.
643 Result last = resultsFromServer[resultsFromServer.length - 1];
644 Result partial = last.isPartial() ? last : null;
645
646 if (LOG.isTraceEnabled()) {
647 StringBuilder sb = new StringBuilder();
648 sb.append("number results from RPC: ").append(resultsFromServer.length).append(",");
649 sb.append("partial != null: ").append(partial != null).append(",");
650 sb.append("number of partials so far: ").append(partialResults.size());
651 LOG.trace(sb.toString());
652 }
653
654 // There are three possibilities cases that can occur while handling partial results
655 //
656 // 1. (partial != null && partialResults.isEmpty())
657 // This is the first partial result that we have received. It should be added to
658 // the list of partialResults and await the next RPC request at which point another
659 // portion of the complete result will be received
660 //
661 // 2. !partialResults.isEmpty()
662 // Since our partialResults list is not empty it means that we have been accumulating partial
663 // Results for a particular row. We cannot form the complete/whole Result for that row until
664 // all partials for the row have been received. Thus we loop through all of the Results
665 // returned from the server and determine whether or not all partial Results for the row have
666 // been received. We know that we have received all of the partial Results for the row when:
667 // i) We notice a row change in the Results
668 // ii) We see a Result for the partial row that is NOT marked as a partial Result
669 //
670 // 3. (partial == null && partialResults.isEmpty())
671 // Business as usual. We are not accumulating partial results and there wasn't a partial result
672 // in the RPC response. This means that all of the results we received from the server are
673 // complete and can be added directly to the cache
674 if (partial != null && partialResults.isEmpty()) {
675 addToPartialResults(partial);
676
677 // Exclude the last result, it's a partial
678 addResultsToList(resultsToAddToCache, resultsFromServer, 0, resultsFromServer.length - 1);
679 } else if (!partialResults.isEmpty()) {
680 for (int i = 0; i < resultsFromServer.length; i++) {
681 Result result = resultsFromServer[i];
682
683 // This result is from the same row as the partial Results. Add it to the list of partials
684 // and check if it was the last partial Result for that row
685 if (Bytes.equals(partialResultsRow, result.getRow())) {
686 addToPartialResults(result);
687
688 // If the result is not a partial, it is a signal to us that it is the last Result we
689 // need to form the complete Result client-side
690 if (!result.isPartial()) {
691 resultsToAddToCache.add(Result.createCompleteResult(partialResults));
692 clearPartialResults();
693 }
694 } else {
695 // The row of this result differs from the row of the partial results we have received so
696 // far. If our list of partials isn't empty, this is a signal to form the complete Result
697 // since the row has now changed
698 if (!partialResults.isEmpty()) {
699 resultsToAddToCache.add(Result.createCompleteResult(partialResults));
700 clearPartialResults();
701 }
702
703 // It's possible that in one response from the server we receive the final partial for
704 // one row and receive a partial for a different row. Thus, make sure that all Results
705 // are added to the proper list
706 if (result.isPartial()) {
707 addToPartialResults(result);
708 } else {
709 resultsToAddToCache.add(result);
710 }
711 }
712 }
713 } else { // partial == null && partialResults.isEmpty() -- business as usual
714 addResultsToList(resultsToAddToCache, resultsFromServer, 0, resultsFromServer.length);
715 }
716
717 return resultsToAddToCache;
718 }
719
720 /**
721 * A convenience method for adding a Result to our list of partials. This method ensure that only
722 * Results that belong to the same row as the other partials can be added to the list.
723 * @param result The result that we want to add to our list of partial Results
724 * @throws IOException
725 */
726 private void addToPartialResults(final Result result) throws IOException {
727 final byte[] row = result.getRow();
728 if (partialResultsRow != null && !Bytes.equals(row, partialResultsRow)) {
729 throw new IOException("Partial result row does not match. All partial results must come "
730 + "from the same row. partialResultsRow: " + Bytes.toString(partialResultsRow) + "row: "
731 + Bytes.toString(row));
732 }
733 partialResultsRow = row;
734 partialResults.add(result);
735 }
736
737 /**
738 * Convenience method for clearing the list of partials and resetting the partialResultsRow.
739 */
740 private void clearPartialResults() {
741 partialResults.clear();
742 partialResultsRow = null;
743 }
744
745 /**
746 * Helper method for adding results between the indices [start, end) to the outputList
747 * @param outputList the list that results will be added to
748 * @param inputArray the array that results are taken from
749 * @param start beginning index (inclusive)
750 * @param end ending index (exclusive)
751 */
752 private void addResultsToList(List<Result> outputList, Result[] inputArray, int start, int end) {
753 if (inputArray == null || start < 0 || end > inputArray.length) return;
754
755 for (int i = start; i < end; i++) {
756 outputList.add(inputArray[i]);
757 }
758 }
759
760 @Override
761 public void close() {
762 if (!scanMetricsPublished) writeScanMetrics();
763 if (callable != null) {
764 callable.setClose();
765 try {
766 call(callable, caller, scannerTimeout);
767 } catch (UnknownScannerException e) {
768 // We used to catch this error, interpret, and rethrow. However, we
769 // have since decided that it's not nice for a scanner's close to
770 // throw exceptions. Chances are it was just due to lease time out.
771 } catch (IOException e) {
772 /* An exception other than UnknownScanner is unexpected. */
773 LOG.warn("scanner failed to close. Exception follows: " + e);
774 }
775 callable = null;
776 }
777 closed = true;
778 }
779
780 /**
781 * Create the closest row before the specified row
782 * @param row
783 * @return a new byte array which is the closest front row of the specified one
784 */
785 protected static byte[] createClosestRowBefore(byte[] row) {
786 if (row == null) {
787 throw new IllegalArgumentException("The passed row is empty");
788 }
789 if (Bytes.equals(row, HConstants.EMPTY_BYTE_ARRAY)) {
790 return MAX_BYTE_ARRAY;
791 }
792 if (row[row.length - 1] == 0) {
793 return Arrays.copyOf(row, row.length - 1);
794 } else {
795 byte[] closestFrontRow = Arrays.copyOf(row, row.length);
796 closestFrontRow[row.length - 1] = (byte) ((closestFrontRow[row.length - 1] & 0xff) - 1);
797 closestFrontRow = Bytes.add(closestFrontRow, MAX_BYTE_ARRAY);
798 return closestFrontRow;
799 }
800 }
801
802 @Override
803 public boolean renewLease() {
804 if (callable != null) {
805 // do not return any rows, do not advance the scanner
806 callable.setRenew(true);
807 try {
808 this.caller.callWithoutRetries(callable, this.scannerTimeout);
809 } catch (Exception e) {
810 return false;
811 } finally {
812 callable.setRenew(false);
813 }
814 return true;
815 }
816 return false;
817 }
818
819 protected void updateLastCellLoadedToCache(Result result) {
820 if (result.rawCells().length == 0) {
821 return;
822 }
823 this.lastCellLoadedToCache = result.rawCells()[result.rawCells().length - 1];
824 }
825
826 /**
827 * Compare two Cells considering reversed scanner.
828 * ReversedScanner only reverses rows, not columns.
829 */
830 private int compare(Cell a, Cell b) {
831 int r = 0;
832 if (currentRegion != null && currentRegion.isMetaRegion()) {
833 r = metaComparator.compareRows(a, b);
834 } else {
835 r = CellComparator.compareRows(a, b);
836 }
837 if (r != 0) {
838 return this.scan.isReversed() ? -r : r;
839 }
840 return CellComparator.compareWithoutRow(a, b);
841 }
842
843 private Result filterLoadedCell(Result result) {
844 // we only filter result when last result is partial
845 // so lastCellLoadedToCache and result should have same row key.
846 // However, if 1) read some cells; 1.1) delete this row at the same time 2) move region;
847 // 3) read more cell. lastCellLoadedToCache and result will be not at same row.
848 if (lastCellLoadedToCache == null || result.rawCells().length == 0) {
849 return result;
850 }
851 if (compare(this.lastCellLoadedToCache, result.rawCells()[0]) < 0) {
852 // The first cell of this result is larger than the last cell of loadcache.
853 // If user do not allow partial result, it must be true.
854 return result;
855 }
856 if (compare(this.lastCellLoadedToCache, result.rawCells()[result.rawCells().length - 1]) >= 0) {
857 // The last cell of this result is smaller than the last cell of loadcache, skip all.
858 return null;
859 }
860
861 // The first one must not in filtered result, we start at the second.
862 int index = 1;
863 while (index < result.rawCells().length) {
864 if (compare(this.lastCellLoadedToCache, result.rawCells()[index]) < 0) {
865 break;
866 }
867 index++;
868 }
869 Cell[] list = Arrays.copyOfRange(result.rawCells(), index, result.rawCells().length);
870 return Result.create(list, result.getExists(), result.isStale(), result.isPartial());
871 }
872 }