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  
21  package org.apache.hadoop.hbase.coprocessor;
22  
23  import java.io.IOException;
24  
25  import org.apache.hadoop.hbase.KeyValue;
26  import org.apache.hadoop.hbase.client.coprocessor.LongColumnInterpreter;
27  import org.apache.hadoop.io.Writable;
28  
29  /**
30   * Defines how value for specific column is interpreted and provides utility
31   * methods like compare, add, multiply etc for them. Takes column family, column
32   * qualifier and return the cell value. Its concrete implementation should
33   * handle null case gracefully. Refer to {@link LongColumnInterpreter} for an
34   * example.
35   * <p>
36   * Takes two generic parameters. The cell value type of the interpreter is <T>.
37   * During some computations like sum, average, the return type can be different
38   * than the cell value data type, for eg, sum of int cell values might overflow
39   * in case of a int result, we should use Long for its result. Therefore, this
40   * class mandates to use a different (promoted) data type for result of these
41   * computations <S>. All computations are performed on the promoted data type
42   * <S>. There is a conversion method
43   * {@link ColumnInterpreter#castToReturnType(Object)} which takes a <T> type and
44   * returns a <S> type.
45   * @param <T> Cell value data type
46   * @param <S> Promoted data type
47   */
48  public interface ColumnInterpreter<T, S> extends Writable {
49  
50    /**
51     * @param colFamily
52     * @param colQualifier
53     * @param kv
54     * @return value of type T
55     * @throws IOException
56     */
57    T getValue(byte[] colFamily, byte[] colQualifier, KeyValue kv)
58        throws IOException;
59  
60    /**
61     * @param l1
62     * @param l2
63     * @return sum or non null value among (if either of them is null); otherwise
64     * returns a null.
65     */
66    public S add(S l1, S l2);
67  
68    /**
69     * returns the maximum value for this type T
70     * @return max
71     */
72  
73    T getMaxValue();
74  
75    T getMinValue();
76  
77    /**
78     * @param o1
79     * @param o2
80     * @return multiplication
81     */
82    S multiply(S o1, S o2);
83  
84    /**
85     * @param o
86     * @return increment
87     */
88    S increment(S o);
89  
90    /**
91     * provides casting opportunity between the data types.
92     * @param o
93     * @return cast
94     */
95    S castToReturnType(T o);
96  
97    /**
98     * This takes care if either of arguments are null. returns 0 if they are
99     * equal or both are null;
100    * <ul>
101    * <li>>0 if l1 > l2 or l1 is not null and l2 is null.
102    * <li>< 0 if l1 < l2 or l1 is null and l2 is not null.
103    */
104   int compare(final T l1, final T l2);
105 
106   /**
107    * used for computing average of <S> data values. Not providing the divide
108    * method that takes two <S> values as it is not needed as of now.
109    * @param o
110    * @param l
111    * @return Average
112    */
113   double divideForAvg(S o, Long l);
114 }