001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.regionserver;
019
020import java.io.IOException;
021import java.util.Collection;
022import java.util.List;
023import java.util.Map;
024import org.apache.hadoop.conf.Configuration;
025import org.apache.hadoop.hbase.Cell;
026import org.apache.hadoop.hbase.CellComparator;
027import org.apache.hadoop.hbase.CompareOperator;
028import org.apache.hadoop.hbase.HBaseInterfaceAudience;
029import org.apache.hadoop.hbase.client.Append;
030import org.apache.hadoop.hbase.client.CheckAndMutate;
031import org.apache.hadoop.hbase.client.CheckAndMutateResult;
032import org.apache.hadoop.hbase.client.CompactionState;
033import org.apache.hadoop.hbase.client.Delete;
034import org.apache.hadoop.hbase.client.Get;
035import org.apache.hadoop.hbase.client.Increment;
036import org.apache.hadoop.hbase.client.Mutation;
037import org.apache.hadoop.hbase.client.Put;
038import org.apache.hadoop.hbase.client.RegionInfo;
039import org.apache.hadoop.hbase.client.Result;
040import org.apache.hadoop.hbase.client.RowMutations;
041import org.apache.hadoop.hbase.client.Scan;
042import org.apache.hadoop.hbase.client.TableDescriptor;
043import org.apache.hadoop.hbase.conf.ConfigurationObserver;
044import org.apache.hadoop.hbase.coprocessor.RegionCoprocessor;
045import org.apache.hadoop.hbase.filter.ByteArrayComparable;
046import org.apache.hadoop.hbase.filter.Filter;
047import org.apache.hadoop.hbase.io.TimeRange;
048import org.apache.hadoop.hbase.regionserver.compactions.CompactionLifeCycleTracker;
049import org.apache.yetus.audience.InterfaceAudience;
050import org.apache.yetus.audience.InterfaceStability;
051
052/**
053 * Region is a subset of HRegion with operations required for the {@link RegionCoprocessor
054 * Coprocessors}. The operations include ability to do mutations, requesting compaction, getting
055 * different counters/sizes, locking rows and getting access to {@linkplain Store}s.
056 */
057@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
058@InterfaceStability.Evolving
059public interface Region extends ConfigurationObserver {
060
061  ///////////////////////////////////////////////////////////////////////////
062  // Region state
063
064  /** Returns region information for this region */
065  RegionInfo getRegionInfo();
066
067  /** Returns table descriptor for this region */
068  TableDescriptor getTableDescriptor();
069
070  /** Returns true if region is available (not closed and not closing) */
071  boolean isAvailable();
072
073  /** Returns true if region is closed */
074  boolean isClosed();
075
076  /** Returns True if closing process has started */
077  boolean isClosing();
078
079  /** Returns True if region is read only */
080  boolean isReadOnly();
081
082  /** Returns true if region is splittable */
083  boolean isSplittable();
084
085  /** Returns true if region is mergeable */
086  boolean isMergeable();
087
088  /**
089   * Return the list of Stores managed by this region
090   * <p>
091   * Use with caution. Exposed for use of fixup utilities.
092   * @return a list of the Stores managed by this region
093   */
094  List<? extends Store> getStores();
095
096  /**
097   * Return the Store for the given family
098   * <p>
099   * Use with caution. Exposed for use of fixup utilities.
100   * @return the Store for the given family
101   */
102  Store getStore(byte[] family);
103
104  /** Returns list of store file names for the given families */
105  List<String> getStoreFileList(byte[][] columns);
106
107  /**
108   * Check the region's underlying store files, open the files that have not been opened yet, and
109   * remove the store file readers for store files no longer available. n
110   */
111  boolean refreshStoreFiles() throws IOException;
112
113  /**
114   * @return the max sequence id of flushed data on this region; no edit in memory will have a
115   *         sequence id that is less that what is returned here.
116   */
117  long getMaxFlushedSeqId();
118
119  /**
120   * This can be used to determine the last time all files of this region were major compacted.
121   * @param majorCompactionOnly Only consider HFile that are the result of major compaction
122   * @return the timestamp of the oldest HFile for all stores of this region
123   */
124  long getOldestHfileTs(boolean majorCompactionOnly) throws IOException;
125
126  /**
127   * @return map of column family names to max sequence id that was read from storage when this
128   *         region was opened
129   */
130  public Map<byte[], Long> getMaxStoreSeqId();
131
132  /**
133   * @return The earliest time a store in the region was flushed. All other stores in the region
134   *         would have been flushed either at, or after this time.
135   */
136  long getEarliestFlushTimeForAllStores();
137
138  ///////////////////////////////////////////////////////////////////////////
139  // Metrics
140
141  /** Returns read requests count for this region */
142  long getReadRequestsCount();
143
144  /** Returns filtered read requests count for this region */
145  long getFilteredReadRequestsCount();
146
147  /** Returns write request count for this region */
148  long getWriteRequestsCount();
149
150  /**
151   * @return memstore size for this region, in bytes. It just accounts data size of cells added to
152   *         the memstores of this Region. Means size in bytes for key, value and tags within Cells.
153   *         It wont consider any java heap overhead for the cell objects or any other.
154   */
155  long getMemStoreDataSize();
156
157  /**
158   * @return memstore heap size for this region, in bytes. It accounts data size of cells added to
159   *         the memstores of this Region, as well as java heap overhead for the cell objects or any
160   *         other.
161   */
162  long getMemStoreHeapSize();
163
164  /**
165   * @return memstore off-heap size for this region, in bytes. It accounts data size of cells added
166   *         to the memstores of this Region, as well as overhead for the cell objects or any other
167   *         that is allocated off-heap.
168   */
169  long getMemStoreOffHeapSize();
170
171  /** Returns the number of mutations processed bypassing the WAL */
172  long getNumMutationsWithoutWAL();
173
174  /** Returns the size of data processed bypassing the WAL, in bytes */
175  long getDataInMemoryWithoutWAL();
176
177  /** Returns the number of blocked requests */
178  long getBlockedRequestsCount();
179
180  /** Returns the number of checkAndMutate guards that passed */
181  long getCheckAndMutateChecksPassed();
182
183  /** Returns the number of failed checkAndMutate guards */
184  long getCheckAndMutateChecksFailed();
185
186  ///////////////////////////////////////////////////////////////////////////
187  // Locking
188
189  // Region read locks
190
191  /**
192   * Operation enum is used in {@link Region#startRegionOperation} and elsewhere to provide context
193   * for various checks.
194   */
195  enum Operation {
196    ANY,
197    GET,
198    PUT,
199    DELETE,
200    SCAN,
201    APPEND,
202    INCREMENT,
203    SPLIT_REGION,
204    MERGE_REGION,
205    BATCH_MUTATE,
206    REPLAY_BATCH_MUTATE,
207    COMPACT_REGION,
208    REPLAY_EVENT,
209    SNAPSHOT,
210    COMPACT_SWITCH,
211    CHECK_AND_MUTATE
212  }
213
214  /**
215   * This method needs to be called before any public call that reads or modifies data. Acquires a
216   * read lock and checks if the region is closing or closed.
217   * <p>
218   * {@link #closeRegionOperation} MUST then always be called after the operation has completed,
219   * whether it succeeded or failed. n
220   */
221  // TODO Exposing this and closeRegionOperation() as we have getRowLock() exposed.
222  // Remove if we get rid of exposing getRowLock().
223  void startRegionOperation() throws IOException;
224
225  /**
226   * This method needs to be called before any public call that reads or modifies data. Acquires a
227   * read lock and checks if the region is closing or closed.
228   * <p>
229   * {@link #closeRegionOperation} MUST then always be called after the operation has completed,
230   * whether it succeeded or failed.
231   * @param op The operation is about to be taken on the region n
232   */
233  void startRegionOperation(Operation op) throws IOException;
234
235  /**
236   * Closes the region operation lock. n
237   */
238  void closeRegionOperation() throws IOException;
239
240  /**
241   * Closes the region operation lock. This needs to be called in the finally block corresponding to
242   * the try block of {@link #startRegionOperation(Operation)} n
243   */
244  void closeRegionOperation(Operation op) throws IOException;
245
246  // Row write locks
247
248  /**
249   * Row lock held by a given thread. One thread may acquire multiple locks on the same row
250   * simultaneously. The locks must be released by calling release() from the same thread.
251   */
252  public interface RowLock {
253    /**
254     * Release the given lock. If there are no remaining locks held by the current thread then
255     * unlock the row and allow other threads to acquire the lock.
256     * @throws IllegalArgumentException if called by a different thread than the lock owning thread
257     */
258    void release();
259  }
260
261  /**
262   * Get a row lock for the specified row. All locks are reentrant. Before calling this function
263   * make sure that a region operation has already been started (the calling thread has already
264   * acquired the region-close-guard lock).
265   * <p>
266   * The obtained locks should be released after use by {@link RowLock#release()}
267   * <p>
268   * NOTE: the boolean passed here has changed. It used to be a boolean that stated whether or not
269   * to wait on the lock. Now it is whether it an exclusive lock is requested.
270   * @param row      The row actions will be performed against
271   * @param readLock is the lock reader or writer. True indicates that a non-exclusive lock is
272   *                 requested
273   * @see #startRegionOperation()
274   * @see #startRegionOperation(Operation)
275   */
276  // TODO this needs to be exposed as we have RowProcessor now. If RowProcessor is removed, we can
277  // remove this too..
278  RowLock getRowLock(byte[] row, boolean readLock) throws IOException;
279
280  ///////////////////////////////////////////////////////////////////////////
281  // Region operations
282
283  /**
284   * Perform one or more append operations on a row. n * @return result of the operation n
285   */
286  Result append(Append append) throws IOException;
287
288  /**
289   * Perform a batch of mutations.
290   * <p>
291   * Please do not operate on a same column of a single row in a batch, we will not consider the
292   * previous operation in the same batch when performing the operations in the batch.
293   * @param mutations the list of mutations
294   * @return an array of OperationStatus which internally contains the OperationStatusCode and the
295   *         exceptionMessage if any. n
296   */
297  OperationStatus[] batchMutate(Mutation[] mutations) throws IOException;
298
299  /**
300   * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it
301   * performs the mutation. If the passed value is null, the lack of column value (ie:
302   * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single
303   * row.
304   * @param row        to check
305   * @param family     column family to check
306   * @param qualifier  column qualifier to check
307   * @param op         the comparison operator
308   * @param comparator the expected value
309   * @param mutation   data to put if check succeeds
310   * @return true if mutation was applied, false otherwise
311   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
312   *             {@link #checkAndMutate(CheckAndMutate)} instead.
313   */
314  @Deprecated
315  default boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
316    ByteArrayComparable comparator, Mutation mutation) throws IOException {
317    return checkAndMutate(row, family, qualifier, op, comparator, TimeRange.allTime(), mutation);
318  }
319
320  /**
321   * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it
322   * performs the mutation. If the passed value is null, the lack of column value (ie:
323   * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single
324   * row.
325   * @param row        to check
326   * @param family     column family to check
327   * @param qualifier  column qualifier to check
328   * @param op         the comparison operator
329   * @param comparator the expected value
330   * @param mutation   data to put if check succeeds
331   * @param timeRange  time range to check
332   * @return true if mutation was applied, false otherwise
333   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
334   *             {@link #checkAndMutate(CheckAndMutate)} instead.
335   */
336  @Deprecated
337  boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
338    ByteArrayComparable comparator, TimeRange timeRange, Mutation mutation) throws IOException;
339
340  /**
341   * Atomically checks if a row matches the filter and if it does, it performs the mutation. See
342   * checkAndRowMutate to do many checkAndPuts at a time on a single row.
343   * @param row      to check
344   * @param filter   the filter
345   * @param mutation data to put if check succeeds
346   * @return true if mutation was applied, false otherwise
347   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
348   *             {@link #checkAndMutate(CheckAndMutate)} instead.
349   */
350  @Deprecated
351  default boolean checkAndMutate(byte[] row, Filter filter, Mutation mutation) throws IOException {
352    return checkAndMutate(row, filter, TimeRange.allTime(), mutation);
353  }
354
355  /**
356   * Atomically checks if a row value matches the filter and if it does, it performs the mutation.
357   * See checkAndRowMutate to do many checkAndPuts at a time on a single row.
358   * @param row       to check
359   * @param filter    the filter
360   * @param mutation  data to put if check succeeds
361   * @param timeRange time range to check
362   * @return true if mutation was applied, false otherwise
363   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
364   *             {@link #checkAndMutate(CheckAndMutate)} instead.
365   */
366  @Deprecated
367  boolean checkAndMutate(byte[] row, Filter filter, TimeRange timeRange, Mutation mutation)
368    throws IOException;
369
370  /**
371   * Atomically checks if a row/family/qualifier value matches the expected values and if it does,
372   * it performs the row mutations. If the passed value is null, the lack of column value (ie:
373   * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one
374   * checkAndMutate at a time.
375   * @param row        to check
376   * @param family     column family to check
377   * @param qualifier  column qualifier to check
378   * @param op         the comparison operator
379   * @param comparator the expected value
380   * @param mutations  data to put if check succeeds
381   * @return true if mutations were applied, false otherwise
382   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
383   *             {@link #checkAndMutate(CheckAndMutate)} instead.
384   */
385  @Deprecated
386  default boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
387    ByteArrayComparable comparator, RowMutations mutations) throws IOException {
388    return checkAndRowMutate(row, family, qualifier, op, comparator, TimeRange.allTime(),
389      mutations);
390  }
391
392  /**
393   * Atomically checks if a row/family/qualifier value matches the expected values and if it does,
394   * it performs the row mutations. If the passed value is null, the lack of column value (ie:
395   * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one
396   * checkAndMutate at a time.
397   * @param row        to check
398   * @param family     column family to check
399   * @param qualifier  column qualifier to check
400   * @param op         the comparison operator
401   * @param comparator the expected value
402   * @param mutations  data to put if check succeeds
403   * @param timeRange  time range to check
404   * @return true if mutations were applied, false otherwise
405   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
406   *             {@link #checkAndMutate(CheckAndMutate)} instead.
407   */
408  @Deprecated
409  boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
410    ByteArrayComparable comparator, TimeRange timeRange, RowMutations mutations) throws IOException;
411
412  /**
413   * Atomically checks if a row matches the filter and if it does, it performs the row mutations.
414   * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a
415   * time.
416   * @param row       to check
417   * @param filter    the filter
418   * @param mutations data to put if check succeeds
419   * @return true if mutations were applied, false otherwise
420   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
421   *             {@link #checkAndMutate(CheckAndMutate)} instead.
422   */
423  @Deprecated
424  default boolean checkAndRowMutate(byte[] row, Filter filter, RowMutations mutations)
425    throws IOException {
426    return checkAndRowMutate(row, filter, TimeRange.allTime(), mutations);
427  }
428
429  /**
430   * Atomically checks if a row matches the filter and if it does, it performs the row mutations.
431   * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a
432   * time.
433   * @param row       to check
434   * @param filter    the filter
435   * @param mutations data to put if check succeeds
436   * @param timeRange time range to check
437   * @return true if mutations were applied, false otherwise
438   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use
439   *             {@link #checkAndMutate(CheckAndMutate)} instead.
440   */
441  @Deprecated
442  boolean checkAndRowMutate(byte[] row, Filter filter, TimeRange timeRange, RowMutations mutations)
443    throws IOException;
444
445  /**
446   * Atomically checks if a row matches the conditions and if it does, it performs the actions. Use
447   * to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a time.
448   * @param checkAndMutate the CheckAndMutate object
449   * @return true if mutations were applied, false otherwise
450   * @throws IOException if an error occurred in this method
451   */
452  CheckAndMutateResult checkAndMutate(CheckAndMutate checkAndMutate) throws IOException;
453
454  /**
455   * Deletes the specified cells/row. nn
456   */
457  void delete(Delete delete) throws IOException;
458
459  /**
460   * Do a get based on the get parameter.
461   * @param get query parameters
462   * @return result of the operation
463   */
464  Result get(Get get) throws IOException;
465
466  /**
467   * Do a get based on the get parameter.
468   * @param get             query parameters
469   * @param withCoprocessor invoke coprocessor or not. We don't want to always invoke cp.
470   * @return list of cells resulting from the operation
471   */
472  List<Cell> get(Get get, boolean withCoprocessor) throws IOException;
473
474  /**
475   * Return an iterator that scans over the HRegion, returning the indicated columns and rows
476   * specified by the {@link Scan}.
477   * <p>
478   * This Iterator must be closed by the caller.
479   * @param scan configured {@link Scan} n * @throws IOException read exceptions
480   */
481  RegionScanner getScanner(Scan scan) throws IOException;
482
483  /**
484   * Return an iterator that scans over the HRegion, returning the indicated columns and rows
485   * specified by the {@link Scan}. The scanner will also include the additional scanners passed
486   * along with the scanners for the specified Scan instance. Should be careful with the usage to
487   * pass additional scanners only within this Region
488   * <p>
489   * This Iterator must be closed by the caller.
490   * @param scan               configured {@link Scan}
491   * @param additionalScanners Any additional scanners to be used n * @throws IOException read
492   *                           exceptions
493   */
494  RegionScanner getScanner(Scan scan, List<KeyValueScanner> additionalScanners) throws IOException;
495
496  /** The comparator to be used with the region */
497  CellComparator getCellComparator();
498
499  /**
500   * Perform one or more increment operations on a row. n * @return result of the operation n
501   */
502  Result increment(Increment increment) throws IOException;
503
504  /**
505   * Performs multiple mutations atomically on a single row.
506   * @param mutations object that specifies the set of mutations to perform atomically
507   * @return results of Increment/Append operations. If no Increment/Append operations, it returns
508   *         null n
509   */
510  Result mutateRow(RowMutations mutations) throws IOException;
511
512  /**
513   * Perform atomic mutations within the region.
514   * @param mutations  The list of mutations to perform. <code>mutations</code> can contain
515   *                   operations for multiple rows. Caller has to ensure that all rows are
516   *                   contained in this region.
517   * @param rowsToLock Rows to lock
518   * @param nonceGroup Optional nonce group of the operation (client Id)
519   * @param nonce      Optional nonce of the operation (unique random id to ensure "more
520   *                   idempotence") If multiple rows are locked care should be taken that
521   *                   <code>rowsToLock</code> is sorted in order to avoid deadlocks. n
522   */
523  // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for
524  // Changing processRowsWithLocks and RowProcessor
525  void mutateRowsWithLocks(Collection<Mutation> mutations, Collection<byte[]> rowsToLock,
526    long nonceGroup, long nonce) throws IOException;
527
528  /**
529   * Performs atomic multiple reads and writes on a given row.
530   * @param processor The object defines the reads and writes to a row.
531   * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use
532   *             Coprocessors instead.
533   */
534  @Deprecated
535  void processRowsWithLocks(RowProcessor<?, ?> processor) throws IOException;
536
537  /**
538   * Performs atomic multiple reads and writes on a given row.
539   * @param processor  The object defines the reads and writes to a row.
540   * @param nonceGroup Optional nonce group of the operation (client Id)
541   * @param nonce      Optional nonce of the operation (unique random id to ensure "more
542   *                   idempotence")
543   * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use
544   *             Coprocessors instead.
545   */
546  // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for
547  // Changing processRowsWithLocks and RowProcessor
548  @Deprecated
549  void processRowsWithLocks(RowProcessor<?, ?> processor, long nonceGroup, long nonce)
550    throws IOException;
551
552  /**
553   * Performs atomic multiple reads and writes on a given row.
554   * @param processor  The object defines the reads and writes to a row.
555   * @param timeout    The timeout of the processor.process() execution Use a negative number to
556   *                   switch off the time bound
557   * @param nonceGroup Optional nonce group of the operation (client Id)
558   * @param nonce      Optional nonce of the operation (unique random id to ensure "more
559   *                   idempotence")
560   * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use
561   *             Coprocessors instead.
562   */
563  // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for
564  // Changing processRowsWithLocks and RowProcessor
565  @Deprecated
566  void processRowsWithLocks(RowProcessor<?, ?> processor, long timeout, long nonceGroup, long nonce)
567    throws IOException;
568
569  /**
570   * Puts some data in the table. nn
571   */
572  void put(Put put) throws IOException;
573
574  ///////////////////////////////////////////////////////////////////////////
575  // Flushes, compactions, splits, etc.
576  // Wizards only, please
577
578  /** Returns if a given region is in compaction now. */
579  CompactionState getCompactionState();
580
581  /**
582   * Request compaction on this region.
583   */
584  void requestCompaction(String why, int priority, boolean major,
585    CompactionLifeCycleTracker tracker) throws IOException;
586
587  /**
588   * Request compaction for the given family
589   */
590  void requestCompaction(byte[] family, String why, int priority, boolean major,
591    CompactionLifeCycleTracker tracker) throws IOException;
592
593  /**
594   * Request flush on this region.
595   */
596  void requestFlush(FlushLifeCycleTracker tracker) throws IOException;
597
598  /**
599   * Wait for all current flushes of the region to complete
600   * @param timeout The maximum time to wait in milliseconds.
601   * @return False when timeout elapsed but flushes are not over. True when flushes are over within
602   *         max wait time period.
603   */
604  boolean waitForFlushes(long timeout);
605
606  /**
607   * @return a read only configuration of this region; throws {@link UnsupportedOperationException}
608   *         if you try to set a configuration.
609   */
610  Configuration getReadOnlyConfiguration();
611}