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 java.io.IOException; 23 24 import org.apache.hadoop.hbase.classification.InterfaceAudience; 25 import org.apache.hadoop.hbase.Cell; 26 27 import com.google.protobuf.Message; 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 34 * {@link org.apache.hadoop.hbase.client.coprocessor.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.Private 57 public abstract class ColumnInterpreter<T, S, P extends Message, 58 Q extends Message, R extends Message> { 59 60 /** 61 * 62 * @param colFamily 63 * @param colQualifier 64 * @param c 65 * @return value of type T 66 * @throws IOException 67 */ 68 public abstract T getValue(byte[] colFamily, byte[] colQualifier, Cell c) 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 org.apache.hadoop.hbase.client.coprocessor.LongColumnInterpreter}) 132 * then null should be returned. 133 * @return the PB message 134 */ 135 public abstract P getRequestData(); 136 137 /** 138 * This method should initialize any field(s) of the ColumnInterpreter with 139 * a parsing of the passed message bytes (used on the server side). 140 * @param msg 141 */ 142 public abstract void initialize(P msg); 143 144 /** 145 * This method gets the PB message corresponding to the cell type 146 * @param t 147 * @return the PB message for the cell-type instance 148 */ 149 public abstract Q getProtoForCellType(T t); 150 151 /** 152 * This method gets the PB message corresponding to the cell type 153 * @param q 154 * @return the cell-type instance from the PB message 155 */ 156 public abstract T getCellValueFromProto(Q q); 157 158 /** 159 * This method gets the PB message corresponding to the promoted type 160 * @param s 161 * @return the PB message for the promoted-type instance 162 */ 163 public abstract R getProtoForPromotedType(S s); 164 165 /** 166 * This method gets the promoted type from the proto message 167 * @param r 168 * @return the promoted-type instance from the PB message 169 */ 170 public abstract S getPromotedValueFromProto(R r); 171 172 /** 173 * The response message comes as type S. This will convert/cast it to T. 174 * In some sense, performs the opposite of {@link #castToReturnType(Object)} 175 * @param response 176 * @return cast 177 */ 178 public abstract T castToCellType(S response); 179 }