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 }