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.
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 coprocessor requests count for this region */
145  long getCpRequestsCount();
146
147  /** Returns filtered read requests count for this region */
148  long getFilteredReadRequestsCount();
149
150  /** Returns write request count for this region */
151  long getWriteRequestsCount();
152
153  /**
154   * @return memstore size for this region, in bytes. It just accounts data size of cells added to
155   *         the memstores of this Region. Means size in bytes for key, value and tags within Cells.
156   *         It wont consider any java heap overhead for the cell objects or any other.
157   */
158  long getMemStoreDataSize();
159
160  /**
161   * @return memstore heap size for this region, in bytes. It accounts data size of cells added to
162   *         the memstores of this Region, as well as java heap overhead for the cell objects or any
163   *         other.
164   */
165  long getMemStoreHeapSize();
166
167  /**
168   * @return memstore off-heap size for this region, in bytes. It accounts data size of cells added
169   *         to the memstores of this Region, as well as overhead for the cell objects or any other
170   *         that is allocated off-heap.
171   */
172  long getMemStoreOffHeapSize();
173
174  /** Returns the number of mutations processed bypassing the WAL */
175  long getNumMutationsWithoutWAL();
176
177  /** Returns the size of data processed bypassing the WAL, in bytes */
178  long getDataInMemoryWithoutWAL();
179
180  /** Returns the number of blocked requests */
181  long getBlockedRequestsCount();
182
183  /** Returns the number of checkAndMutate guards that passed */
184  long getCheckAndMutateChecksPassed();
185
186  /** Returns the number of failed checkAndMutate guards */
187  long getCheckAndMutateChecksFailed();
188
189  ///////////////////////////////////////////////////////////////////////////
190  // Locking
191
192  // Region read locks
193
194  /**
195   * Operation enum is used in {@link Region#startRegionOperation} and elsewhere to provide context
196   * for various checks.
197   */
198  enum Operation {
199    ANY,
200    GET,
201    PUT,
202    DELETE,
203    SCAN,
204    APPEND,
205    INCREMENT,
206    SPLIT_REGION,
207    MERGE_REGION,
208    BATCH_MUTATE,
209    REPLAY_BATCH_MUTATE,
210    COMPACT_REGION,
211    REPLAY_EVENT,
212    SNAPSHOT,
213    COMPACT_SWITCH,
214    CHECK_AND_MUTATE
215  }
216
217  /**
218   * This method needs to be called before any public call that reads or modifies data. Acquires a
219   * read lock and checks if the region is closing or closed.
220   * <p>
221   * {@link #closeRegionOperation} MUST then always be called after the operation has completed,
222   * whether it succeeded or failed.
223   */
224  // TODO Exposing this and closeRegionOperation() as we have getRowLock() exposed.
225  // Remove if we get rid of exposing getRowLock().
226  void startRegionOperation() throws IOException;
227
228  /**
229   * This method needs to be called before any public call that reads or modifies data. Acquires a
230   * read lock and checks if the region is closing or closed.
231   * <p>
232   * {@link #closeRegionOperation} MUST then always be called after the operation has completed,
233   * whether it succeeded or failed.
234   * @param op The operation is about to be taken on the region
235   */
236  void startRegionOperation(Operation op) throws IOException;
237
238  /**
239   * Closes the region operation lock.
240   */
241  void closeRegionOperation() throws IOException;
242
243  /**
244   * Closes the region operation lock. This needs to be called in the finally block corresponding to
245   * the try block of {@link #startRegionOperation(Operation)}
246   */
247  void closeRegionOperation(Operation op) throws IOException;
248
249  // Row write locks
250
251  /**
252   * Row lock held by a given thread. One thread may acquire multiple locks on the same row
253   * simultaneously. The locks must be released by calling release() from the same thread.
254   */
255  public interface RowLock {
256    /**
257     * Release the given lock. If there are no remaining locks held by the current thread then
258     * unlock the row and allow other threads to acquire the lock.
259     * @throws IllegalArgumentException if called by a different thread than the lock owning thread
260     */
261    void release();
262  }
263
264  /**
265   * Get a row lock for the specified row. All locks are reentrant. Before calling this function
266   * make sure that a region operation has already been started (the calling thread has already
267   * acquired the region-close-guard lock).
268   * <p>
269   * The obtained locks should be released after use by {@link RowLock#release()}
270   * <p>
271   * NOTE: the boolean passed here has changed. It used to be a boolean that stated whether or not
272   * to wait on the lock. Now it is whether it an exclusive lock is requested.
273   * @param row      The row actions will be performed against
274   * @param readLock is the lock reader or writer. True indicates that a non-exclusive lock is
275   *                 requested
276   * @see #startRegionOperation()
277   * @see #startRegionOperation(Operation)
278   */
279  RowLock getRowLock(byte[] row, boolean readLock) throws IOException;
280
281  ///////////////////////////////////////////////////////////////////////////
282  // Region operations
283
284  /**
285   * Perform one or more append operations on a row.
286   * @return result of the operation
287   */
288  Result append(Append append) throws IOException;
289
290  /**
291   * Perform a batch of mutations.
292   * <p>
293   * Please do not operate on a same column of a single row in a batch, we will not consider the
294   * previous operation in the same batch when performing the operations in the batch.
295   * @param mutations the list of mutations
296   * @return an array of OperationStatus which internally contains the OperationStatusCode and the
297   *         exceptionMessage if any.
298   */
299  OperationStatus[] batchMutate(Mutation[] mutations) throws IOException;
300
301  /**
302   * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it
303   * performs the mutation. If the passed value is null, the lack of column value (ie:
304   * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single
305   * row.
306   * @param row        to check
307   * @param family     column family to check
308   * @param qualifier  column qualifier to check
309   * @param op         the comparison operator
310   * @param comparator the expected value
311   * @param mutation   data to put if check succeeds
312   * @return true if mutation was applied, false otherwise
313   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
314   *             {@link #checkAndMutate(CheckAndMutate)} instead.
315   */
316  @Deprecated
317  default boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
318    ByteArrayComparable comparator, Mutation mutation) throws IOException {
319    return checkAndMutate(row, family, qualifier, op, comparator, TimeRange.allTime(), mutation);
320  }
321
322  /**
323   * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it
324   * performs the mutation. If the passed value is null, the lack of column value (ie:
325   * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single
326   * row.
327   * @param row        to check
328   * @param family     column family to check
329   * @param qualifier  column qualifier to check
330   * @param op         the comparison operator
331   * @param comparator the expected value
332   * @param mutation   data to put if check succeeds
333   * @param timeRange  time range to check
334   * @return true if mutation was applied, false otherwise
335   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
336   *             {@link #checkAndMutate(CheckAndMutate)} instead.
337   */
338  @Deprecated
339  boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
340    ByteArrayComparable comparator, TimeRange timeRange, Mutation mutation) throws IOException;
341
342  /**
343   * Atomically checks if a row matches the filter and if it does, it performs the mutation. See
344   * checkAndRowMutate to do many checkAndPuts at a time on a single row.
345   * @param row      to check
346   * @param filter   the filter
347   * @param mutation data to put if check succeeds
348   * @return true if mutation was applied, false otherwise
349   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
350   *             {@link #checkAndMutate(CheckAndMutate)} instead.
351   */
352  @Deprecated
353  default boolean checkAndMutate(byte[] row, Filter filter, Mutation mutation) throws IOException {
354    return checkAndMutate(row, filter, TimeRange.allTime(), mutation);
355  }
356
357  /**
358   * Atomically checks if a row value matches the filter and if it does, it performs the mutation.
359   * See checkAndRowMutate to do many checkAndPuts at a time on a single row.
360   * @param row       to check
361   * @param filter    the filter
362   * @param mutation  data to put if check succeeds
363   * @param timeRange time range to check
364   * @return true if mutation was applied, false otherwise
365   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
366   *             {@link #checkAndMutate(CheckAndMutate)} instead.
367   */
368  @Deprecated
369  boolean checkAndMutate(byte[] row, Filter filter, TimeRange timeRange, Mutation mutation)
370    throws IOException;
371
372  /**
373   * Atomically checks if a row/family/qualifier value matches the expected values and if it does,
374   * it performs the row mutations. If the passed value is null, the lack of column value (ie:
375   * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one
376   * checkAndMutate at a time.
377   * @param row        to check
378   * @param family     column family to check
379   * @param qualifier  column qualifier to check
380   * @param op         the comparison operator
381   * @param comparator the expected value
382   * @param mutations  data to put if check succeeds
383   * @return true if mutations were applied, false otherwise
384   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
385   *             {@link #checkAndMutate(CheckAndMutate)} instead.
386   */
387  @Deprecated
388  default boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
389    ByteArrayComparable comparator, RowMutations mutations) throws IOException {
390    return checkAndRowMutate(row, family, qualifier, op, comparator, TimeRange.allTime(),
391      mutations);
392  }
393
394  /**
395   * Atomically checks if a row/family/qualifier value matches the expected values and if it does,
396   * it performs the row mutations. If the passed value is null, the lack of column value (ie:
397   * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one
398   * checkAndMutate at a time.
399   * @param row        to check
400   * @param family     column family to check
401   * @param qualifier  column qualifier to check
402   * @param op         the comparison operator
403   * @param comparator the expected value
404   * @param mutations  data to put if check succeeds
405   * @param timeRange  time range to check
406   * @return true if mutations were applied, false otherwise
407   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
408   *             {@link #checkAndMutate(CheckAndMutate)} instead.
409   */
410  @Deprecated
411  boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op,
412    ByteArrayComparable comparator, TimeRange timeRange, RowMutations mutations) throws IOException;
413
414  /**
415   * Atomically checks if a row matches the filter and if it does, it performs the row mutations.
416   * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a
417   * time.
418   * @param row       to check
419   * @param filter    the filter
420   * @param mutations data to put if check succeeds
421   * @return true if mutations were applied, false otherwise
422   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
423   *             {@link #checkAndMutate(CheckAndMutate)} instead.
424   */
425  @Deprecated
426  default boolean checkAndRowMutate(byte[] row, Filter filter, RowMutations mutations)
427    throws IOException {
428    return checkAndRowMutate(row, filter, TimeRange.allTime(), mutations);
429  }
430
431  /**
432   * Atomically checks if a row matches the filter and if it does, it performs the row mutations.
433   * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a
434   * time.
435   * @param row       to check
436   * @param filter    the filter
437   * @param mutations data to put if check succeeds
438   * @param timeRange time range to check
439   * @return true if mutations were applied, false otherwise
440   * @deprecated since 3.0.0 and will be removed in 4.0.0. Use
441   *             {@link #checkAndMutate(CheckAndMutate)} instead.
442   */
443  @Deprecated
444  boolean checkAndRowMutate(byte[] row, Filter filter, TimeRange timeRange, RowMutations mutations)
445    throws IOException;
446
447  /**
448   * Atomically checks if a row matches the conditions and if it does, it performs the actions. Use
449   * to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a time.
450   * @param checkAndMutate the CheckAndMutate object
451   * @return true if mutations were applied, false otherwise
452   * @throws IOException if an error occurred in this method
453   */
454  CheckAndMutateResult checkAndMutate(CheckAndMutate checkAndMutate) throws IOException;
455
456  /**
457   * Deletes the specified cells/row.
458   */
459  void delete(Delete delete) throws IOException;
460
461  /**
462   * Do a get based on the get parameter.
463   * @param get query parameters
464   * @return result of the operation
465   */
466  Result get(Get get) throws IOException;
467
468  /**
469   * Do a get based on the get parameter.
470   * @param get             query parameters
471   * @param withCoprocessor invoke coprocessor or not. We don't want to always invoke cp.
472   * @return list of cells resulting from the operation
473   */
474  List<Cell> get(Get get, boolean withCoprocessor) throws IOException;
475
476  /**
477   * Return an iterator that scans over the HRegion, returning the indicated columns and rows
478   * specified by the {@link Scan}.
479   * <p>
480   * This Iterator must be closed by the caller.
481   * @param scan configured {@link Scan}
482   * @throws IOException read exceptions
483   */
484  RegionScanner getScanner(Scan scan) throws IOException;
485
486  /**
487   * Return an iterator that scans over the HRegion, returning the indicated columns and rows
488   * specified by the {@link Scan}. The scanner will also include the additional scanners passed
489   * along with the scanners for the specified Scan instance. Should be careful with the usage to
490   * pass additional scanners only within this Region
491   * <p>
492   * This Iterator must be closed by the caller.
493   * @param scan               configured {@link Scan}
494   * @param additionalScanners Any additional scanners to be used
495   * @throws IOException read exceptions
496   */
497  RegionScanner getScanner(Scan scan, List<KeyValueScanner> additionalScanners) throws IOException;
498
499  /** The comparator to be used with the region */
500  CellComparator getCellComparator();
501
502  /**
503   * Perform one or more increment operations on a row.
504   * @return result of the operation
505   */
506  Result increment(Increment increment) throws IOException;
507
508  /**
509   * Performs multiple mutations atomically on a single row.
510   * @param mutations object that specifies the set of mutations to perform atomically
511   * @return results of Increment/Append operations. If no Increment/Append operations, it returns
512   *         null
513   */
514  Result mutateRow(RowMutations mutations) throws IOException;
515
516  /**
517   * Perform atomic mutations within the region.
518   * @param mutations  The list of mutations to perform. <code>mutations</code> can contain
519   *                   operations for multiple rows. Caller has to ensure that all rows are
520   *                   contained in this region.
521   * @param rowsToLock Rows to lock
522   * @param nonceGroup Optional nonce group of the operation (client Id)
523   * @param nonce      Optional nonce of the operation (unique random id to ensure "more
524   *                   idempotence") If multiple rows are locked care should be taken that
525   *                   <code>rowsToLock</code> is sorted in order to avoid deadlocks.
526   */
527  // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for
528  // Changing processRowsWithLocks
529  void mutateRowsWithLocks(Collection<Mutation> mutations, Collection<byte[]> rowsToLock,
530    long nonceGroup, long nonce) throws IOException;
531
532  /**
533   * Puts some data in the table.
534   */
535  void put(Put put) throws IOException;
536
537  ///////////////////////////////////////////////////////////////////////////
538  // Flushes, compactions, splits, etc.
539  // Wizards only, please
540
541  /** Returns if a given region is in compaction now. */
542  CompactionState getCompactionState();
543
544  /**
545   * Request compaction on this region.
546   */
547  void requestCompaction(String why, int priority, boolean major,
548    CompactionLifeCycleTracker tracker) throws IOException;
549
550  /**
551   * Request compaction for the given family
552   */
553  void requestCompaction(byte[] family, String why, int priority, boolean major,
554    CompactionLifeCycleTracker tracker) throws IOException;
555
556  /**
557   * Request flush on this region.
558   */
559  void requestFlush(FlushLifeCycleTracker tracker) throws IOException;
560
561  /**
562   * Wait for all current flushes of the region to complete
563   * @param timeout The maximum time to wait in milliseconds.
564   * @return False when timeout elapsed but flushes are not over. True when flushes are over within
565   *         max wait time period.
566   */
567  boolean waitForFlushes(long timeout);
568
569  /**
570   * @return a read only configuration of this region; throws {@link UnsupportedOperationException}
571   *         if you try to set a configuration.
572   */
573  Configuration getReadOnlyConfiguration();
574}