org.apache.hadoop.hbase.filter
Class Filter

java.lang.Object
  extended by org.apache.hadoop.hbase.filter.Filter
Direct Known Subclasses:
FilterBase, FilterList, FilterWrapper

@InterfaceAudience.Public
@InterfaceStability.Stable
public abstract class Filter
extends Object

Interface for row and column filters directly applied within the regionserver. A filter can expect the following call sequence:

Filter instances are created one per region/scan. This abstract class replaces the old RowFilterInterface. When implementing your own filters, consider inheriting FilterBase to help you reduce boilerplate.

See Also:
FilterBase

Nested Class Summary
static class Filter.ReturnCode
          Return codes for filterValue().
 
Constructor Summary
Filter()
           
 
Method Summary
abstract  boolean filterAllRemaining()
          If this returns true, the scan will terminate.
abstract  Filter.ReturnCode filterKeyValue(KeyValue v)
          A way to filter based on the column family, column qualifier and/or the column value.
abstract  boolean filterRow()
          Last chance to veto row based on previous filterKeyValue(KeyValue) calls.
abstract  void filterRow(List<KeyValue> kvs)
          Chance to alter the list of keyvalues to be submitted.
abstract  boolean filterRowKey(byte[] buffer, int offset, int length)
          Filters a row based on the row key.
abstract  KeyValue getNextKeyHint(KeyValue currentKV)
          If the filter returns the match code SEEK_NEXT_USING_HINT, then it should also tell which is the next key it must seek to.
abstract  boolean hasFilterRow()
          Primarily used to check for conflicts with scans(such as scans that do not read a full row at a time).
abstract  boolean isFamilyEssential(byte[] name)
          Check that given column family is essential for filter to check row.
static Filter parseFrom(byte[] pbBytes)
          Concrete implementers can signal a failure condition in their code by throwing an IOException.
abstract  void reset()
          Reset the state of the filter between rows.
abstract  byte[] toByteArray()
          TODO: JAVADOC Concrete implementers can signal a failure condition in their code by throwing an IOException.
abstract  KeyValue transform(KeyValue v)
          Give the filter a chance to transform the passed KeyValue.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Filter

public Filter()
Method Detail

reset

public abstract void reset()
                    throws IOException
Reset the state of the filter between rows. Concrete implementers can signal a failure condition in their code by throwing an IOException.

Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

filterRowKey

public abstract boolean filterRowKey(byte[] buffer,
                                     int offset,
                                     int length)
                              throws IOException
Filters a row based on the row key. If this returns true, the entire row will be excluded. If false, each KeyValue in the row will be passed to filterKeyValue(KeyValue) below. Concrete implementers can signal a failure condition in their code by throwing an IOException.

Parameters:
buffer - buffer containing row key
offset - offset into buffer where row key starts
length - length of the row key
Returns:
true, remove entire row, false, include the row (maybe).
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

filterAllRemaining

public abstract boolean filterAllRemaining()
                                    throws IOException
If this returns true, the scan will terminate. Concrete implementers can signal a failure condition in their code by throwing an IOException.

Returns:
true to end scan, false to continue.
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

filterKeyValue

public abstract Filter.ReturnCode filterKeyValue(KeyValue v)
                                          throws IOException
A way to filter based on the column family, column qualifier and/or the column value. Return code is described below. This allows filters to filter only certain number of columns, then terminate without matching ever column. If your filter returns ReturnCode.NEXT_ROW, it should return ReturnCode.NEXT_ROW until reset() is called just in case the caller calls for the next row. Concrete implementers can signal a failure condition in their code by throwing an IOException.

Parameters:
v - the KeyValue in question
Returns:
code as described below
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.
See Also:
Filter.ReturnCode

transform

public abstract KeyValue transform(KeyValue v)
                            throws IOException
Give the filter a chance to transform the passed KeyValue. If the KeyValue is changed a new KeyValue object must be returned.

Parameters:
v - the KeyValue in question
Returns:
the changed KeyValue
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.
See Also:
The transformed KeyValue is what is eventually returned to the client. Most filters will return the passed KeyValue unchanged., for an example of a transformation. Concrete implementers can signal a failure condition in their code by throwing an {@link IOException}.

filterRow

public abstract void filterRow(List<KeyValue> kvs)
                        throws IOException
Chance to alter the list of keyvalues to be submitted. Modifications to the list will carry on Concrete implementers can signal a failure condition in their code by throwing an IOException.

Parameters:
kvs - the list of keyvalues to be filtered
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

hasFilterRow

public abstract boolean hasFilterRow()
Primarily used to check for conflicts with scans(such as scans that do not read a full row at a time).

Returns:
True if this filter actively uses filterRow(List) or filterRow().

filterRow

public abstract boolean filterRow()
                           throws IOException
Last chance to veto row based on previous filterKeyValue(KeyValue) calls. The filter needs to retain state then return a particular value for this call if they wish to exclude a row if a certain column is missing (for example). Concrete implementers can signal a failure condition in their code by throwing an IOException.

Returns:
true to exclude row, false to include row.
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

getNextKeyHint

public abstract KeyValue getNextKeyHint(KeyValue currentKV)
                                 throws IOException
If the filter returns the match code SEEK_NEXT_USING_HINT, then it should also tell which is the next key it must seek to. After receiving the match code SEEK_NEXT_USING_HINT, the QueryMatcher would call this function to find out which key it must next seek to. Concrete implementers can signal a failure condition in their code by throwing an IOException.

Returns:
KeyValue which must be next seeked. return null if the filter is not sure which key to seek to next.
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

isFamilyEssential

public abstract boolean isFamilyEssential(byte[] name)
                                   throws IOException
Check that given column family is essential for filter to check row. Most filters always return true here. But some could have more sophisticated logic which could significantly reduce scanning process by not even touching columns until we are 100% sure that it's data is needed in result. Concrete implementers can signal a failure condition in their code by throwing an IOException.

Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

toByteArray

public abstract byte[] toByteArray()
                            throws IOException
TODO: JAVADOC Concrete implementers can signal a failure condition in their code by throwing an IOException.

Returns:
The filter serialized using pb
Throws:
IOException - in case an I/O or an filter specific failure needs to be signaled.

parseFrom

public static Filter parseFrom(byte[] pbBytes)
                        throws DeserializationException
Concrete implementers can signal a failure condition in their code by throwing an IOException.

Parameters:
pbBytes - A pb serialized Filter instance
Returns:
An instance of Filter made from bytes
Throws:
DeserializationException
IOException - in case an I/O or an filter specific failure needs to be signaled.
See Also:
toByteArray()


Copyright © 2013 The Apache Software Foundation. All Rights Reserved.