View Javadoc

1   /**
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  
20  package org.apache.hadoop.hbase.filter;
21  
22  import java.util.ArrayList;
23  
24  import org.apache.hadoop.hbase.classification.InterfaceAudience;
25  import org.apache.hadoop.hbase.classification.InterfaceStability;
26  import org.apache.hadoop.hbase.protobuf.ProtobufUtil;
27  import org.apache.hadoop.hbase.protobuf.generated.FilterProtos;
28  import org.apache.hadoop.hbase.protobuf.generated.HBaseProtos;
29  import org.apache.hadoop.hbase.protobuf.generated.HBaseProtos.CompareType;
30  import org.apache.hadoop.hbase.util.Bytes;
31  
32  import com.google.common.base.Preconditions;
33  /**
34   * This is a generic filter to be used to filter by comparison.  It takes an
35   * operator (equal, greater, not equal, etc) and a byte [] comparator.
36   * <p>
37   * To filter by row key, use {@link RowFilter}.
38   * <p>
39   * To filter by column qualifier, use {@link QualifierFilter}.
40   * <p>
41   * To filter by value, use {@link SingleColumnValueFilter}.
42   * <p>
43   * These filters can be wrapped with {@link SkipFilter} and {@link WhileMatchFilter}
44   * to add more control.
45   * <p>
46   * Multiple filters can be combined using {@link FilterList}.
47   */
48  @InterfaceAudience.Public
49  @InterfaceStability.Stable
50  public abstract class CompareFilter extends FilterBase {
51  
52    /** Comparison operators. */
53    @InterfaceAudience.Public
54    @InterfaceStability.Stable
55    public enum CompareOp {
56      /** less than */
57      LESS,
58      /** less than or equal to */
59      LESS_OR_EQUAL,
60      /** equals */
61      EQUAL,
62      /** not equal */
63      NOT_EQUAL,
64      /** greater than or equal to */
65      GREATER_OR_EQUAL,
66      /** greater than */
67      GREATER,
68      /** no operation */
69      NO_OP,
70    }
71  
72    protected CompareOp compareOp;
73    protected ByteArrayComparable comparator;
74  
75    /**
76     * Constructor.
77     * @param compareOp the compare op for row matching
78     * @param comparator the comparator for row matching
79     */
80    public CompareFilter(final CompareOp compareOp,
81        final ByteArrayComparable comparator) {
82      this.compareOp = compareOp;
83      this.comparator = comparator;
84    }
85  
86    /**
87     * @return operator
88     */
89    public CompareOp getOperator() {
90      return compareOp;
91    }
92  
93    /**
94     * @return the comparator
95     */
96    public ByteArrayComparable getComparator() {
97      return comparator;
98    }
99  
100   protected boolean doCompare(final CompareOp compareOp,
101       final ByteArrayComparable comparator, final byte [] data,
102       final int offset, final int length) {
103     if (compareOp == CompareOp.NO_OP) {
104       return true;
105     }
106     int compareResult = comparator.compareTo(data, offset, length);
107     switch (compareOp) {
108       case LESS:
109         return compareResult <= 0;
110       case LESS_OR_EQUAL:
111         return compareResult < 0;
112       case EQUAL:
113         return compareResult != 0;
114       case NOT_EQUAL:
115         return compareResult == 0;
116       case GREATER_OR_EQUAL:
117         return compareResult > 0;
118       case GREATER:
119         return compareResult >= 0;
120       default:
121         throw new RuntimeException("Unknown Compare op " +
122           compareOp.name());
123     }
124   }
125 
126   // returns an array of heterogeneous objects
127   public static ArrayList<Object> extractArguments(ArrayList<byte []> filterArguments) {
128     Preconditions.checkArgument(filterArguments.size() == 2,
129                                 "Expected 2 but got: %s", filterArguments.size());
130     CompareOp compareOp = ParseFilter.createCompareOp(filterArguments.get(0));
131     ByteArrayComparable comparator = ParseFilter.createComparator(
132       ParseFilter.removeQuotesFromByteArray(filterArguments.get(1)));
133 
134     if (comparator instanceof RegexStringComparator ||
135         comparator instanceof SubstringComparator) {
136       if (compareOp != CompareOp.EQUAL &&
137           compareOp != CompareOp.NOT_EQUAL) {
138         throw new IllegalArgumentException ("A regexstring comparator and substring comparator" +
139                                             " can only be used with EQUAL and NOT_EQUAL");
140       }
141     }
142     ArrayList<Object> arguments = new ArrayList<Object>();
143     arguments.add(compareOp);
144     arguments.add(comparator);
145     return arguments;
146   }
147 
148   /**
149    * @return A pb instance to represent this instance.
150    */
151   FilterProtos.CompareFilter convert() {
152     FilterProtos.CompareFilter.Builder builder =
153       FilterProtos.CompareFilter.newBuilder();
154     HBaseProtos.CompareType compareOp = CompareType.valueOf(this.compareOp.name());
155     builder.setCompareOp(compareOp);
156     if (this.comparator != null) builder.setComparator(ProtobufUtil.toComparator(this.comparator));
157     return builder.build();
158   }
159 
160   /**
161    *
162    * @param o
163    * @return true if and only if the fields of the filter that are serialized
164    * are equal to the corresponding fields in other.  Used for testing.
165    */
166   boolean areSerializedFieldsEqual(Filter o) {
167     if (o == this) return true;
168     if (!(o instanceof CompareFilter)) return false;
169 
170     CompareFilter other = (CompareFilter)o;
171     return this.getOperator().equals(other.getOperator()) &&
172       (this.getComparator() == other.getComparator()
173         || this.getComparator().areSerializedFieldsEqual(other.getComparator()));
174   }
175 
176   @Override
177   public String toString() {
178     return String.format("%s (%s, %s)",
179         this.getClass().getSimpleName(),
180         this.compareOp.name(),
181         Bytes.toStringBinary(this.comparator.getValue()));
182   }
183 }