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    * Close a scanner
332    *
333    * @param scannerId the scanner id returned by openScanner
334    * @throws IOException e
335    */
336   public void close(long scannerId) throws IOException;
337 
338   /**
339    * Opens a remote row lock.
340    *
341    * @param regionName name of region
342    * @param row row to lock
343    * @return lockId lock identifier
344    * @throws IOException e
345    */
346   public long lockRow(final byte [] regionName, final byte [] row)
347   throws IOException;
348 
349   /**
350    * Releases a remote row lock.
351    *
352    * @param regionName region name
353    * @param lockId the lock id returned by lockRow
354    * @throws IOException e
355    */
356   public void unlockRow(final byte [] regionName, final long lockId)
357   throws IOException;
358 
359 
360   /**
361    * @return All regions online on this region server
362    * @throws IOException e
363    */
364   public List<HRegionInfo> getOnlineRegions() throws IOException;
365 
366   /**
367    * Method used when a master is taking the place of another failed one.
368    * @return This servers {@link HServerInfo}; it has RegionServer POV on the
369    * hostname which may not agree w/ how the Master sees this server.
370    * @throws IOException e
371    * @deprecated
372    */
373   public HServerInfo getHServerInfo() throws IOException;
374 
375   /**
376    * Method used for doing multiple actions(Deletes, Gets and Puts) in one call
377    * @param multi
378    * @return MultiResult
379    * @throws IOException
380    */
381   public <R> MultiResponse multi(MultiAction<R> multi) throws IOException;
382 
383   /**
384    * Atomically bulk load multiple HFiles (say from different column families)
385    * into an open region.
386    * 
387    * @param familyPaths List of (family, hfile path) pairs
388    * @param regionName name of region to load hfiles into
389    * @return true if successful, false if failed recoverably
390    * @throws IOException if fails unrecoverably
391    */
392   public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName)
393   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    * @param assignSeqNum should we assign sequence numbers
402    * @return true if successful, false if failed recoverably
403    * @throws IOException if fails unrecoverably
404    */
405    public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName,
406        boolean assignSeqNum)
407   throws IOException;
408 
409 
410   // Master methods
411 
412   /**
413    * Opens the specified region.
414    * 
415    * @param region
416    *          region to open
417    * @return RegionOpeningState 
418    *         OPENED         - if region open request was successful.
419    *         ALREADY_OPENED - if the region was already opened. 
420    *         FAILED_OPENING - if region opening failed.
421    *
422    * @throws IOException
423    */
424   public RegionOpeningState openRegion(final HRegionInfo region) throws IOException;
425 
426   /**
427    * Opens the specified region.
428    * @param region
429    *          region to open
430    * @param versionOfOfflineNode
431    *          the version of znode to compare when RS transitions the znode from
432    *          OFFLINE state.
433    * @return RegionOpeningState 
434    *         OPENED         - if region open request was successful.
435    *         ALREADY_OPENED - if the region was already opened. 
436    *         FAILED_OPENING - if region opening failed.
437    * @throws IOException
438    */
439   public RegionOpeningState openRegion(HRegionInfo region, int versionOfOfflineNode)
440       throws IOException;
441   
442   /**
443    * Opens the specified regions.
444    * @param regions regions to open
445    * @throws IOException
446    */
447   public void openRegions(final List<HRegionInfo> regions) throws IOException;
448 
449   /**
450    * Closes the specified region.
451    * @param region region to close
452    * @return true if closing region, false if not
453    * @throws IOException
454    */
455   public boolean closeRegion(final HRegionInfo region)
456   throws IOException;
457 
458   /**
459    * Closes the specified region.
460    * @param region region to close
461    * @param versionOfClosingNode
462    *          the version of znode to compare when RS transitions the znode
463    *          from CLOSING state.
464    * @return true if closing region, false if not
465    * @throws IOException
466    */
467   public boolean closeRegion(final HRegionInfo region,
468     final int versionOfClosingNode)
469   throws IOException;
470 
471   /**
472    * Closes the specified region and will use or not use ZK during the close
473    * according to the specified flag.
474    * @param region region to close
475    * @param zk true if transitions should be done in ZK, false if not
476    * @return true if closing region, false if not
477    * @throws IOException
478    */
479   public boolean closeRegion(final HRegionInfo region, final boolean zk)
480   throws IOException;
481   
482   /**
483    * Closes the region in the RS with the specified encoded regionName and will
484    * use or not use ZK during the close according to the specified flag. Note
485    * that the encoded region name is in byte format.
486    * 
487    * @param encodedRegionName
488    *          in bytes
489    * @param zk
490    *          true if to use zookeeper, false if need not.
491    * @return true if region is closed, false if not.
492    * @throws IOException
493    */
494   public boolean closeRegion(byte[] encodedRegionName, final boolean zk)
495       throws IOException;
496 
497   // Region administrative methods
498 
499   /**
500    * Flushes the MemStore of the specified region.
501    * <p>
502    * This method is synchronous.
503    * @param regionInfo region to flush
504    * @throws NotServingRegionException
505    * @throws IOException
506    * @deprecated use {@link #flushRegion(byte[])} instead
507    */
508   void flushRegion(HRegionInfo regionInfo)
509   throws NotServingRegionException, IOException;
510 
511   /**
512    * Splits the specified region.
513    * <p>
514    * This method currently flushes the region and then forces a compaction which
515    * will then trigger a split.  The flush is done synchronously but the
516    * compaction is asynchronous.
517    * @param regionInfo region to split
518    * @throws NotServingRegionException
519    * @throws IOException
520    */
521   void splitRegion(HRegionInfo regionInfo)
522   throws NotServingRegionException, IOException;
523 
524   /**
525    * Splits the specified region.
526    * <p>
527    * This method currently flushes the region and then forces a compaction which
528    * will then trigger a split.  The flush is done synchronously but the
529    * compaction is asynchronous.
530    * @param regionInfo region to split
531    * @param splitPoint the explicit row to split on
532    * @throws NotServingRegionException
533    * @throws IOException
534    */
535   void splitRegion(HRegionInfo regionInfo, byte[] splitPoint)
536   throws NotServingRegionException, IOException;
537 
538   /**
539    * Compacts the specified region.  Performs a major compaction if specified.
540    * <p>
541    * This method is asynchronous.
542    * @param regionInfo region to compact
543    * @param major true to force major compaction
544    * @throws NotServingRegionException
545    * @throws IOException
546    */
547   void compactRegion(HRegionInfo regionInfo, boolean major)
548   throws NotServingRegionException, IOException;
549 
550   /**
551    * Compacts a column-family within a specified region.
552    * Performs a major compaction if specified.
553    * <p>
554    * This method is asynchronous.
555    * @param regionInfo region to compact
556    * @param major true to force major compaction
557    * @param columnFamily column family within a region to compact
558    * @throws NotServingRegionException
559    * @throws IOException
560    */
561   void compactRegion(HRegionInfo regionInfo, boolean major, byte[] columnFamily)
562   throws NotServingRegionException, IOException;
563    
564   /**
565    * Replicates the given entries. The guarantee is that the given entries
566    * will be durable on the slave cluster if this method returns without
567    * any exception.
568    * hbase.replication has to be set to true for this to work.
569    *
570    * @param entries entries to replicate
571    * @throws IOException
572    */
573   public void replicateLogEntries(HLog.Entry[] entries) throws IOException;
574 
575   /**
576    * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol}
577    * method using the registered protocol handlers.
578    * {@link CoprocessorProtocol} implementations must be registered via the
579    * {@link org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)}
580    * method before they are available.
581    *
582    * @param regionName name of the region against which the invocation is executed
583    * @param call an {@code Exec} instance identifying the protocol, method name,
584    *     and parameters for the method invocation
585    * @return an {@code ExecResult} instance containing the region name of the
586    *     invocation and the return value
587    * @throws IOException if no registered protocol handler is found or an error
588    *     occurs during the invocation
589    * @see org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)
590    */
591   ExecResult execCoprocessor(byte[] regionName, Exec call)
592       throws IOException;
593 
594   /**
595    * Atomically checks if a row/family/qualifier value match the expectedValue.
596    * If it does, it adds the put. If passed expected value is null, then the
597    * check is for non-existance of the row/column.
598    *
599    * @param regionName
600    * @param row
601    * @param family
602    * @param qualifier
603    * @param compareOp
604    * @param comparator
605    * @param put
606    * @throws IOException
607    * @return true if the new put was execute, false otherwise
608    */
609   public boolean checkAndPut(final byte[] regionName, final byte[] row,
610       final byte[] family, final byte[] qualifier, final CompareOp compareOp,
611       final WritableByteArrayComparable comparator, final Put put)
612   throws IOException;
613 
614   /**
615    * Atomically checks if a row/family/qualifier value match the expectedValue.
616    * If it does, it adds the delete. If passed expected value is null, then the
617    * check is for non-existance of the row/column.
618    *
619    * @param regionName
620    * @param row
621    * @param family
622    * @param qualifier
623    * @param compareOp
624    * @param comparator
625    * @param delete
626    * @throws IOException
627    * @return true if the new put was execute, false otherwise
628    */
629   public boolean checkAndDelete(final byte[] regionName, final byte[] row,
630      final byte[] family, final byte[] qualifier, final CompareOp compareOp,
631      final WritableByteArrayComparable comparator, final Delete delete)
632      throws IOException;
633   
634   /**
635    * Performs a BlockCache summary and returns a List of BlockCacheColumnFamilySummary objects.
636    * This method could be fairly heavyweight in that it evaluates the entire HBase file-system
637    * against what is in the RegionServer BlockCache. 
638    * 
639    * @return BlockCacheColumnFamilySummary
640    * @throws IOException exception
641    */
642   public List<BlockCacheColumnFamilySummary> getBlockCacheColumnFamilySummaries() throws IOException;
643   /**
644    * Roll the log writer. That is, start writing log messages to a new file.
645    * 
646    * @throws IOException
647    * @throws FailedLogCloseException
648    * @return If lots of logs, flush the returned regions so next time through
649    * we can clean logs. Returns null if nothing to flush.  Names are actual
650    * region names as returned by {@link HRegionInfo#getEncodedName()} 
651    */
652   public byte[][] rollHLogWriter() throws IOException, FailedLogCloseException;
653 
654   /**
655    * Get the current compaction state of the region.
656    *
657    * @param regionName the name of the region to check compaction statte.
658    * @return the compaction state name.
659    * @throws IOException exception
660    */
661   public String getCompactionState(final byte[] regionName) throws IOException;
662 
663   @Override
664   public void stop(String why);
665 
666   /**
667    * Perform scan operation.
668    * @param regionName name of region to get from
669    * @param Scan scan operation
670    * @param numberOfRows the maximum number of rows to fetch
671    * @return Array of Results;array is empty if done with this region and null
672    *         if we are NOT to go to the next region (happens when a filter rules
673    *         that the scan is done).
674    * @throws IOException e
675    */
676   public Result[] scan(byte[] regionName, Scan scan, int numberOfRows)
677       throws IOException;
678 }