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.coprocessor;
21
22 import com.google.protobuf.Message;
23 import org.apache.hadoop.classification.InterfaceAudience;
24 import org.apache.hadoop.classification.InterfaceStability;
25 import org.apache.hadoop.hbase.KeyValue;
26 import org.apache.hadoop.hbase.client.coprocessor.LongColumnInterpreter;
27
28 import java.io.IOException;
29
30 /**
31 * Defines how value for specific column is interpreted and provides utility
32 * methods like compare, add, multiply etc for them. Takes column family, column
33 * qualifier and return the cell value. Its concrete implementation should
34 * handle null case gracefully. Refer to {@link LongColumnInterpreter} for an
35 * example.
36 * <p>
37 * Takes two generic parameters and three Message parameters.
38 * The cell value type of the interpreter is <T>.
39 * During some computations like sum, average, the return type can be different
40 * than the cell value data type, for eg, sum of int cell values might overflow
41 * in case of a int result, we should use Long for its result. Therefore, this
42 * class mandates to use a different (promoted) data type for result of these
43 * computations <S>. All computations are performed on the promoted data type
44 * <S>. There is a conversion method
45 * {@link ColumnInterpreter#castToReturnType(Object)} which takes a <T> type and
46 * returns a <S> type.
47 * The AggregateImplementation uses PB messages to initialize the
48 * user's ColumnInterpreter implementation, and for sending the responses
49 * back to AggregationClient.
50 * @param <T> Cell value data type
51 * @param <S> Promoted data type
52 * @param <P> PB message that is used to transport initializer specific bytes
53 * @param <Q> PB message that is used to transport Cell (<T>) instance
54 * @param <R> PB message that is used to transport Promoted (<S>) instance
55 */
56 @InterfaceAudience.Public
57 @InterfaceStability.Evolving
58 public abstract class ColumnInterpreter<T, S, P extends Message,
59 Q extends Message, R extends Message> {
60
61 /**
62 * @param colFamily
63 * @param colQualifier
64 * @param kv
65 * @return value of type T
66 * @throws IOException
67 */
68 public abstract T getValue(byte[] colFamily, byte[] colQualifier, KeyValue kv)
69 throws IOException;
70
71 /**
72 * @param l1
73 * @param l2
74 * @return sum or non null value among (if either of them is null); otherwise
75 * returns a null.
76 */
77 public abstract S add(S l1, S l2);
78
79 /**
80 * returns the maximum value for this type T
81 * @return max
82 */
83
84 public abstract T getMaxValue();
85
86 public abstract T getMinValue();
87
88 /**
89 * @param o1
90 * @param o2
91 * @return multiplication
92 */
93 public abstract S multiply(S o1, S o2);
94
95 /**
96 * @param o
97 * @return increment
98 */
99 public abstract S increment(S o);
100
101 /**
102 * provides casting opportunity between the data types.
103 * @param o
104 * @return cast
105 */
106 public abstract S castToReturnType(T o);
107
108 /**
109 * This takes care if either of arguments are null. returns 0 if they are
110 * equal or both are null;
111 * <ul>
112 * <li>>0 if l1 > l2 or l1 is not null and l2 is null.
113 * <li>< 0 if l1 < l2 or l1 is null and l2 is not null.
114 */
115 public abstract int compare(final T l1, final T l2);
116
117 /**
118 * used for computing average of <S> data values. Not providing the divide
119 * method that takes two <S> values as it is not needed as of now.
120 * @param o
121 * @param l
122 * @return Average
123 */
124 public abstract double divideForAvg(S o, Long l);
125
126 /**
127 * This method should return any additional data that is needed on the
128 * server side to construct the ColumnInterpreter. The server
129 * will pass this to the {@link #initialize}
130 * method. If there is no ColumnInterpreter specific data (for e.g.,
131 * {@link LongColumnInterpreter}) then null should be returned.
132 * @return the PB message
133 */
134 public abstract P getRequestData();
135
136 /**
137 * This method should initialize any field(s) of the ColumnInterpreter with
138 * a parsing of the passed message bytes (used on the server side).
139 * @param msg
140 */
141 public abstract void initialize(P msg);
142
143 /**
144 * This method gets the PB message corresponding to the cell type
145 * @param t
146 * @return the PB message for the cell-type instance
147 */
148 public abstract Q getProtoForCellType(T t);
149
150 /**
151 * This method gets the PB message corresponding to the cell type
152 * @param q
153 * @return the cell-type instance from the PB message
154 */
155 public abstract T getCellValueFromProto(Q q);
156
157 /**
158 * This method gets the PB message corresponding to the promoted type
159 * @param s
160 * @return the PB message for the promoted-type instance
161 */
162 public abstract R getProtoForPromotedType(S s);
163
164 /**
165 * This method gets the promoted type from the proto message
166 * @param r
167 * @return the promoted-type instance from the PB message
168 */
169 public abstract S getPromotedValueFromProto(R r);
170
171 /**
172 * The response message comes as type S. This will convert/cast it to T.
173 * In some sense, performs the opposite of {@link #castToReturnType(Object)}
174 * @param response
175 * @return cast
176 */
177 public abstract T castToCellType(S response);
178 }