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 }