View Javadoc

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 java.io.IOException;
23  import java.net.ConnectException;
24  import java.util.List;
25  
26  import org.apache.hadoop.hbase.Abortable;
27  import org.apache.hadoop.hbase.HRegionInfo;
28  import org.apache.hadoop.hbase.HServerInfo;
29  import org.apache.hadoop.hbase.NotServingRegionException;
30  import org.apache.hadoop.hbase.Stoppable;
31  import org.apache.hadoop.hbase.client.Append;
32  import org.apache.hadoop.hbase.client.RowMutations;
33  import org.apache.hadoop.hbase.client.Delete;
34  import org.apache.hadoop.hbase.client.Get;
35  import org.apache.hadoop.hbase.client.Increment;
36  import org.apache.hadoop.hbase.client.MultiAction;
37  import org.apache.hadoop.hbase.client.MultiResponse;
38  import org.apache.hadoop.hbase.client.Put;
39  import org.apache.hadoop.hbase.client.Result;
40  import org.apache.hadoop.hbase.client.Scan;
41  import org.apache.hadoop.hbase.client.coprocessor.Exec;
42  import org.apache.hadoop.hbase.client.coprocessor.ExecResult;
43  import org.apache.hadoop.hbase.filter.CompareFilter.CompareOp;
44  import org.apache.hadoop.hbase.filter.WritableByteArrayComparable;
45  import org.apache.hadoop.hbase.io.hfile.BlockCacheColumnFamilySummary;
46  import org.apache.hadoop.hbase.regionserver.RegionOpeningState;
47  import org.apache.hadoop.hbase.regionserver.compactions.CompactionRequest.CompactionState;
48  import org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException;
49  import org.apache.hadoop.hbase.regionserver.wal.HLog;
50  import org.apache.hadoop.hbase.security.TokenInfo;
51  import org.apache.hadoop.hbase.security.KerberosInfo;
52  import org.apache.hadoop.hbase.util.Pair;
53  import org.apache.hadoop.ipc.RemoteException;
54  import org.apache.hadoop.hbase.ipc.VersionedProtocol;
55  
56  /**
57   * Clients interact with HRegionServers using a handle to the HRegionInterface.
58   *
59   * <p>NOTE: if you change the interface, you must change the RPC version
60   * number in HBaseRPCProtocolVersion
61   */
62  @KerberosInfo(
63      serverPrincipal = "hbase.regionserver.kerberos.principal")
64  @TokenInfo("HBASE_AUTH_TOKEN")
65  public interface HRegionInterface extends VersionedProtocol, Stoppable, Abortable {
66    /**
67     * This Interfaces' version. Version changes when the Interface changes.
68     */
69    // All HBase Interfaces used derive from HBaseRPCProtocolVersion.  It
70    // maintained a single global version number on all HBase Interfaces.  This
71    // meant all HBase RPC was broke though only one of the three RPC Interfaces
72    // had changed.  This has since been undone.
73    public static final long VERSION = 29L;
74  
75    /**
76     * Get metainfo about an HRegion
77     *
78     * @param regionName name of the region
79     * @return HRegionInfo object for region
80     * @throws NotServingRegionException
81     * @throws ConnectException
82     * @throws IOException This can manifest as an Hadoop ipc {@link RemoteException}
83     */
84    public HRegionInfo getRegionInfo(final byte [] regionName)
85    throws NotServingRegionException, ConnectException, IOException;
86  
87    /**
88     * Flush the given region
89     * @param region name
90     */
91    public void flushRegion(byte[] regionName)
92      throws IllegalArgumentException, IOException;
93  
94    /**
95     * Flush the given region if lastFlushTime < ifOlderThanTS
96     * @param region name
97     * @param timestamp
98     */
99    public void flushRegion(byte[] regionName, long ifOlderThanTS)
100     throws IllegalArgumentException, IOException;
101 
102   /**
103    * Gets last flush time for the given region
104    * @return the last flush time for a region
105    */
106   public long getLastFlushTime(byte[] regionName);
107 
108   /**
109    * Get a list of store files for a particular CF in a particular region
110    * @param region name
111    * @param CF name
112    * @return the list of store files
113    */
114   public List<String> getStoreFileList(byte[] regionName, byte[] columnFamily)
115     throws IllegalArgumentException;
116 
117   /**
118    * Get a list of store files for a set of CFs in a particular region
119    * @param region name
120    * @param CF names
121    * @return the list of store files
122    */
123   public List<String> getStoreFileList(byte[] regionName, byte[][] columnFamilies)
124     throws IllegalArgumentException;
125 
126   /**
127    * Get a list of store files for all CFs in a particular region
128    * @param region name
129    * @return the list of store files
130    */
131   public List<String> getStoreFileList(byte[] regionName)
132     throws IllegalArgumentException;
133 
134   /**
135    * Return all the data for the row that matches <i>row</i> exactly,
136    * or the one that immediately preceeds it.
137    *
138    * @param regionName region name
139    * @param row row key
140    * @param family Column family to look for row in.
141    * @return map of values
142    * @throws IOException e
143    */
144   public Result getClosestRowBefore(final byte [] regionName,
145     final byte [] row, final byte [] family)
146   throws IOException;
147 
148   /**
149    * Perform Get operation.
150    * @param regionName name of region to get from
151    * @param get Get operation
152    * @return Result
153    * @throws IOException e
154    */
155   public Result get(byte [] regionName, Get get) throws IOException;
156 
157   /**
158    * Perform exists operation.
159    * @param regionName name of region to get from
160    * @param get Get operation describing cell to test
161    * @return true if exists
162    * @throws IOException e
163    */
164   public boolean exists(byte [] regionName, Get get) throws IOException;
165 
166   /**
167    * Put data into the specified region
168    * @param regionName region name
169    * @param put the data to be put
170    * @throws IOException e
171    */
172   public void put(final byte [] regionName, final Put put)
173   throws IOException;
174 
175   /**
176    * Put an array of puts into the specified region
177    *
178    * @param regionName region name
179    * @param puts List of puts to execute
180    * @return The number of processed put's.  Returns -1 if all Puts
181    * processed successfully.
182    * @throws IOException e
183    */
184   public int put(final byte[] regionName, final List<Put> puts)
185   throws IOException;
186 
187   /**
188    * Deletes all the KeyValues that match those found in the Delete object,
189    * if their ts <= to the Delete. In case of a delete with a specific ts it
190    * only deletes that specific KeyValue.
191    * @param regionName region name
192    * @param delete delete object
193    * @throws IOException e
194    */
195   public void delete(final byte[] regionName, final Delete delete)
196   throws IOException;
197 
198   /**
199    * Put an array of deletes into the specified region
200    *
201    * @param regionName region name
202    * @param deletes delete List to execute
203    * @return The number of processed deletes.  Returns -1 if all Deletes
204    * processed successfully.
205    * @throws IOException e
206    */
207   public int delete(final byte[] regionName, final List<Delete> deletes)
208   throws IOException;
209 
210   /**
211    * Atomically checks if a row/family/qualifier value match the expectedValue.
212    * If it does, it adds the put. If passed expected value is null, then the
213    * check is for non-existance of the row/column.
214    *
215    * @param regionName region name
216    * @param row row to check
217    * @param family column family
218    * @param qualifier column qualifier
219    * @param value the expected value
220    * @param put data to put if check succeeds
221    * @throws IOException e
222    * @return true if the new put was execute, false otherwise
223    */
224   public boolean checkAndPut(final byte[] regionName, final byte [] row,
225       final byte [] family, final byte [] qualifier, final byte [] value,
226       final Put put)
227   throws IOException;
228 
229 
230   /**
231    * Atomically checks if a row/family/qualifier value match the expectedValue.
232    * If it does, it adds the delete. If passed expected value is null, then the
233    * check is for non-existance of the row/column.
234    *
235    * @param regionName region name
236    * @param row row to check
237    * @param family column family
238    * @param qualifier column qualifier
239    * @param value the expected value
240    * @param delete data to delete if check succeeds
241    * @throws IOException e
242    * @return true if the new delete was execute, false otherwise
243    */
244   public boolean checkAndDelete(final byte[] regionName, final byte [] row,
245       final byte [] family, final byte [] qualifier, final byte [] value,
246       final Delete delete)
247   throws IOException;
248 
249   /**
250    * Atomically increments a column value. If the column value isn't long-like,
251    * this could throw an exception. If passed expected value is null, then the
252    * check is for non-existance of the row/column.
253    *
254    * @param regionName region name
255    * @param row row to check
256    * @param family column family
257    * @param qualifier column qualifier
258    * @param amount long amount to increment
259    * @param writeToWAL whether to write the increment to the WAL
260    * @return new incremented column value
261    * @throws IOException e
262    */
263   public long incrementColumnValue(byte [] regionName, byte [] row,
264       byte [] family, byte [] qualifier, long amount, boolean writeToWAL)
265   throws IOException;
266 
267   public void mutateRow(byte[] regionName, RowMutations rm)
268       throws IOException;
269 
270   /**
271    * Appends values to one or more columns values in a row. Optionally
272    * Returns the updated keys after the append.
273    * <p>
274    * This operation does not appear atomic to readers. Appends are done
275    * under a row lock but readers do not take row locks.
276    * @param regionName region name
277    * @param append Append operation
278    * @return changed cells (maybe null)
279    */
280   public Result append(byte[] regionName, Append append)
281   throws IOException;
282 
283   /**
284    * Increments one or more columns values in a row.  Returns the
285    * updated keys after the increment.
286    * <p>
287    * This operation does not appear atomic to readers.  Increments are done
288    * under a row lock but readers do not take row locks.
289    * @param regionName region name
290    * @param increment increment operation
291    * @return incremented cells
292    */
293   public Result increment(byte[] regionName, Increment increment)
294   throws IOException;
295 
296   //
297   // remote scanner interface
298   //
299 
300   /**
301    * Opens a remote scanner with a RowFilter.
302    *
303    * @param regionName name of region to scan
304    * @param scan configured scan object
305    * @return scannerId scanner identifier used in other calls
306    * @throws IOException e
307    */
308   public long openScanner(final byte [] regionName, final Scan scan)
309   throws IOException;
310 
311   /**
312    * Get the next set of values
313    * @param scannerId clientId passed to openScanner
314    * @return map of values; returns null if no results.
315    * @throws IOException e
316    */
317   public Result next(long scannerId) throws IOException;
318 
319   /**
320    * Get the next set of values
321    * @param scannerId clientId passed to openScanner
322    * @param numberOfRows the number of rows to fetch
323    * @return Array of Results (map of values); array is empty if done with this
324    * region and null if we are NOT to go to the next region (happens when a
325    * filter rules that the scan is done).
326    * @throws IOException e
327    */
328   public Result [] next(long scannerId, int numberOfRows) throws IOException;
329 
330   /**
331    * Get the next set of values
332    * @param scannerId clientId passed to openScanner
333    * @param numberOfRows the number of rows to fetch
334    * @param callSeq the number which represents the sequence used by client scanner
335    * @return Array of Results (map of values); array is empty if done with this
336    * region and null if we are NOT to go to the next region (happens when a
337    * filter rules that the scan is done).
338    * @throws IOException e
339    */
340   public Result[] next(long scannerId, int caching, long callSeq) throws IOException;
341 
342   /**
343    * Close a scanner
344    *
345    * @param scannerId the scanner id returned by openScanner
346    * @throws IOException e
347    */
348   public void close(long scannerId) throws IOException;
349 
350   /**
351    * Opens a remote row lock.
352    *
353    * @param regionName name of region
354    * @param row row to lock
355    * @return lockId lock identifier
356    * @throws IOException e
357    */
358   public long lockRow(final byte [] regionName, final byte [] row)
359   throws IOException;
360 
361   /**
362    * Releases a remote row lock.
363    *
364    * @param regionName region name
365    * @param lockId the lock id returned by lockRow
366    * @throws IOException e
367    */
368   public void unlockRow(final byte [] regionName, final long lockId)
369   throws IOException;
370 
371 
372   /**
373    * @return All regions online on this region server
374    * @throws IOException e
375    */
376   public List<HRegionInfo> getOnlineRegions() throws IOException;
377 
378   /**
379    * Method used when a master is taking the place of another failed one.
380    * @return This servers {@link HServerInfo}; it has RegionServer POV on the
381    * hostname which may not agree w/ how the Master sees this server.
382    * @throws IOException e
383    * @deprecated
384    */
385   public HServerInfo getHServerInfo() throws IOException;
386 
387   /**
388    * Method used for doing multiple actions(Deletes, Gets and Puts) in one call
389    * @param multi
390    * @return MultiResult
391    * @throws IOException
392    */
393   public <R> MultiResponse multi(MultiAction<R> multi) throws IOException;
394 
395   /**
396    * Atomically bulk load multiple HFiles (say from different column families)
397    * into an open region.
398    * 
399    * @param familyPaths List of (family, hfile path) pairs
400    * @param regionName name of region to load hfiles into
401    * @return true if successful, false if failed recoverably
402    * @throws IOException if fails unrecoverably
403    */
404   public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName)
405   throws IOException;
406 
407   /**
408    * Atomically bulk load multiple HFiles (say from different column families)
409    * into an open region.
410    * 
411    * @param familyPaths List of (family, hfile path) pairs
412    * @param regionName name of region to load hfiles into
413    * @param assignSeqNum should we assign sequence numbers
414    * @return true if successful, false if failed recoverably
415    * @throws IOException if fails unrecoverably
416    */
417    public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName,
418        boolean assignSeqNum)
419   throws IOException;
420 
421 
422   // Master methods
423 
424   /**
425    * Opens the specified region.
426    * 
427    * @param region
428    *          region to open
429    * @return RegionOpeningState 
430    *         OPENED         - if region open request was successful.
431    *         ALREADY_OPENED - if the region was already opened. 
432    *         FAILED_OPENING - if region opening failed.
433    *
434    * @throws IOException
435    */
436   public RegionOpeningState openRegion(final HRegionInfo region) throws IOException;
437 
438   /**
439    * Opens the specified region.
440    * @param region
441    *          region to open
442    * @param versionOfOfflineNode
443    *          the version of znode to compare when RS transitions the znode from
444    *          OFFLINE state.
445    * @return RegionOpeningState 
446    *         OPENED         - if region open request was successful.
447    *         ALREADY_OPENED - if the region was already opened. 
448    *         FAILED_OPENING - if region opening failed.
449    * @throws IOException
450    */
451   public RegionOpeningState openRegion(HRegionInfo region, int versionOfOfflineNode)
452       throws IOException;
453   
454   /**
455    * Opens the specified regions.
456    * @param regions regions to open
457    * @throws IOException
458    */
459   public void openRegions(final List<HRegionInfo> regions) throws IOException;
460 
461   /**
462    * Closes the specified region.
463    * @param region region to close
464    * @return true if closing region, false if not
465    * @throws IOException
466    */
467   public boolean closeRegion(final HRegionInfo region)
468   throws IOException;
469 
470   /**
471    * Closes the specified region.
472    * @param region region to close
473    * @param versionOfClosingNode
474    *          the version of znode to compare when RS transitions the znode
475    *          from CLOSING state.
476    * @return true if closing region, false if not
477    * @throws IOException
478    */
479   public boolean closeRegion(final HRegionInfo region,
480     final int versionOfClosingNode)
481   throws IOException;
482 
483   /**
484    * Closes the specified region and will use or not use ZK during the close
485    * according to the specified flag.
486    * @param region region to close
487    * @param zk true if transitions should be done in ZK, false if not
488    * @return true if closing region, false if not
489    * @throws IOException
490    */
491   public boolean closeRegion(final HRegionInfo region, final boolean zk)
492   throws IOException;
493   
494   /**
495    * Closes the region in the RS with the specified encoded regionName and will
496    * use or not use ZK during the close according to the specified flag. Note
497    * that the encoded region name is in byte format.
498    * 
499    * @param encodedRegionName
500    *          in bytes
501    * @param zk
502    *          true if to use zookeeper, false if need not.
503    * @return true if region is closed, false if not.
504    * @throws IOException
505    */
506   public boolean closeRegion(byte[] encodedRegionName, final boolean zk)
507       throws IOException;
508 
509   // Region administrative methods
510 
511   /**
512    * Flushes the MemStore of the specified region.
513    * <p>
514    * This method is synchronous.
515    * @param regionInfo region to flush
516    * @throws NotServingRegionException
517    * @throws IOException
518    * @deprecated use {@link #flushRegion(byte[])} instead
519    */
520   void flushRegion(HRegionInfo regionInfo)
521   throws NotServingRegionException, IOException;
522 
523   /**
524    * Splits the specified region.
525    * <p>
526    * This method currently flushes the region and then forces a compaction which
527    * will then trigger a split.  The flush is done synchronously but the
528    * compaction is asynchronous.
529    * @param regionInfo region to split
530    * @throws NotServingRegionException
531    * @throws IOException
532    */
533   void splitRegion(HRegionInfo regionInfo)
534   throws NotServingRegionException, IOException;
535 
536   /**
537    * Splits the specified region.
538    * <p>
539    * This method currently flushes the region and then forces a compaction which
540    * will then trigger a split.  The flush is done synchronously but the
541    * compaction is asynchronous.
542    * @param regionInfo region to split
543    * @param splitPoint the explicit row to split on
544    * @throws NotServingRegionException
545    * @throws IOException
546    */
547   void splitRegion(HRegionInfo regionInfo, byte[] splitPoint)
548   throws NotServingRegionException, IOException;
549 
550   /**
551    * Compacts the specified region.  Performs a major compaction if specified.
552    * <p>
553    * This method is asynchronous.
554    * @param regionInfo region to compact
555    * @param major true to force major compaction
556    * @throws NotServingRegionException
557    * @throws IOException
558    */
559   void compactRegion(HRegionInfo regionInfo, boolean major)
560   throws NotServingRegionException, IOException;
561 
562   /**
563    * Compacts a column-family within a specified region.
564    * Performs a major compaction if specified.
565    * <p>
566    * This method is asynchronous.
567    * @param regionInfo region to compact
568    * @param major true to force major compaction
569    * @param columnFamily column family within a region to compact
570    * @throws NotServingRegionException
571    * @throws IOException
572    */
573   void compactRegion(HRegionInfo regionInfo, boolean major, byte[] columnFamily)
574   throws NotServingRegionException, IOException;
575    
576   /**
577    * Replicates the given entries. The guarantee is that the given entries
578    * will be durable on the slave cluster if this method returns without
579    * any exception.
580    * hbase.replication has to be set to true for this to work.
581    *
582    * @param entries entries to replicate
583    * @throws IOException
584    */
585   public void replicateLogEntries(HLog.Entry[] entries) throws IOException;
586 
587   /**
588    * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol}
589    * method using the registered protocol handlers.
590    * {@link CoprocessorProtocol} implementations must be registered via the
591    * {@link org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)}
592    * method before they are available.
593    *
594    * @param regionName name of the region against which the invocation is executed
595    * @param call an {@code Exec} instance identifying the protocol, method name,
596    *     and parameters for the method invocation
597    * @return an {@code ExecResult} instance containing the region name of the
598    *     invocation and the return value
599    * @throws IOException if no registered protocol handler is found or an error
600    *     occurs during the invocation
601    * @see org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)
602    */
603   ExecResult execCoprocessor(byte[] regionName, Exec call)
604       throws IOException;
605 
606   /**
607    * Atomically checks if a row/family/qualifier value match the expectedValue.
608    * If it does, it adds the put. If passed expected value is null, then the
609    * check is for non-existance of the row/column.
610    *
611    * @param regionName
612    * @param row
613    * @param family
614    * @param qualifier
615    * @param compareOp
616    * @param comparator
617    * @param put
618    * @throws IOException
619    * @return true if the new put was execute, false otherwise
620    */
621   public boolean checkAndPut(final byte[] regionName, final byte[] row,
622       final byte[] family, final byte[] qualifier, final CompareOp compareOp,
623       final WritableByteArrayComparable comparator, final Put put)
624   throws IOException;
625 
626   /**
627    * Atomically checks if a row/family/qualifier value match the expectedValue.
628    * If it does, it adds the delete. If passed expected value is null, then the
629    * check is for non-existance of the row/column.
630    *
631    * @param regionName
632    * @param row
633    * @param family
634    * @param qualifier
635    * @param compareOp
636    * @param comparator
637    * @param delete
638    * @throws IOException
639    * @return true if the new put was execute, false otherwise
640    */
641   public boolean checkAndDelete(final byte[] regionName, final byte[] row,
642      final byte[] family, final byte[] qualifier, final CompareOp compareOp,
643      final WritableByteArrayComparable comparator, final Delete delete)
644      throws IOException;
645   
646   /**
647    * Performs a BlockCache summary and returns a List of BlockCacheColumnFamilySummary objects.
648    * This method could be fairly heavyweight in that it evaluates the entire HBase file-system
649    * against what is in the RegionServer BlockCache. 
650    * 
651    * @return BlockCacheColumnFamilySummary
652    * @throws IOException exception
653    */
654   public List<BlockCacheColumnFamilySummary> getBlockCacheColumnFamilySummaries() throws IOException;
655   /**
656    * Roll the log writer. That is, start writing log messages to a new file.
657    * 
658    * @throws IOException
659    * @throws FailedLogCloseException
660    * @return If lots of logs, flush the returned regions so next time through
661    * we can clean logs. Returns null if nothing to flush.  Names are actual
662    * region names as returned by {@link HRegionInfo#getEncodedName()} 
663    */
664   public byte[][] rollHLogWriter() throws IOException, FailedLogCloseException;
665 
666   /**
667    * Get the current compaction state of the region.
668    *
669    * @param regionName the name of the region to check compaction statte.
670    * @return the compaction state name.
671    * @throws IOException exception
672    */
673   public String getCompactionState(final byte[] regionName) throws IOException;
674 
675   @Override
676   public void stop(String why);
677 
678   /**
679    * Perform scan operation.
680    * @param regionName name of region to get from
681    * @param Scan scan operation
682    * @param numberOfRows the maximum number of rows to fetch
683    * @return Array of Results;array is empty if done with this region and null
684    *         if we are NOT to go to the next region (happens when a filter rules
685    *         that the scan is done).
686    * @throws IOException e
687    */
688   public Result[] scan(byte[] regionName, Scan scan, int numberOfRows)
689       throws IOException;
690 }