001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.apache.hadoop.hbase.coprocessor; 019 020import com.google.protobuf.Message; 021import java.io.IOException; 022import org.apache.hadoop.hbase.Cell; 023import org.apache.hadoop.hbase.HBaseInterfaceAudience; 024import org.apache.yetus.audience.InterfaceAudience; 025import org.apache.yetus.audience.InterfaceStability; 026 027/** 028 * Defines how value for specific column is interpreted and provides utility methods like compare, 029 * add, multiply etc for them. Takes column family, column qualifier and return the cell value. Its 030 * concrete implementation should handle null case gracefully. Refer to 031 * {@link org.apache.hadoop.hbase.client.coprocessor.LongColumnInterpreter} for an example. 032 * <p> 033 * Takes two generic parameters and three Message parameters. The cell value type of the interpreter 034 * is <T>. During some computations like sum, average, the return type can be different than 035 * the cell value data type, for eg, sum of int cell values might overflow in case of a int result, 036 * we should use Long for its result. Therefore, this class mandates to use a different (promoted) 037 * data type for result of these computations <S>. All computations are performed on the 038 * promoted data type <S>. There is a conversion method 039 * {@link ColumnInterpreter#castToReturnType(Object)} which takes a <T> type and returns a 040 * <S> type. The AggregateIm>lementation uses PB messages to initialize the user's 041 * ColumnInterpreter implementation, and for sending the responses back to AggregationClient. 042 * <p> 043 * <T> Cell value data type<br> 044 * <S> Promoted data type<br> 045 * <P> PB message that is used to transport initializer specific bytes<br> 046 * <Q> PB message that is used to transport Cell (<T>) instance<br> 047 * <R> PB message that is used to transport Promoted (<S>) instance 048 */ 049@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC) 050@InterfaceStability.Evolving 051public abstract class ColumnInterpreter<T, S, P extends Message, Q extends Message, 052 R extends Message> { 053 054 /** 055 * nnn * @return value of type T n 056 */ 057 public abstract T getValue(byte[] colFamily, byte[] colQualifier, Cell c) throws IOException; 058 059 /** 060 * nn * @return sum or non null value among (if either of them is null); otherwise returns a null. 061 */ 062 public abstract S add(S l1, S l2); 063 064 /** 065 * returns the maximum value for this type T n 066 */ 067 068 public abstract T getMaxValue(); 069 070 public abstract T getMinValue(); 071 072 /** 073 * nnn 074 */ 075 public abstract S multiply(S o1, S o2); 076 077 /** 078 * nn 079 */ 080 public abstract S increment(S o); 081 082 /** 083 * provides casting opportunity between the data types. nn 084 */ 085 public abstract S castToReturnType(T o); 086 087 /** 088 * This takes care if either of arguments are null. returns 0 if they are equal or both are null; 089 * <ul> 090 * <li>> 0 if l1 > l2 or l1 is not null and l2 is null.</li> 091 * <li>< 0 if l1 < l2 or l1 is null and l2 is not null.</li> 092 * </ul> 093 */ 094 public abstract int compare(final T l1, final T l2); 095 096 /** 097 * used for computing average of <S> data values. Not providing the divide method that takes 098 * two <S> values as it is not needed as of now. nnn 099 */ 100 public abstract double divideForAvg(S o, Long l); 101 102 /** 103 * This method should return any additional data that is needed on the server side to construct 104 * the ColumnInterpreter. The server will pass this to the {@link #initialize} method. If there is 105 * no ColumnInterpreter specific data (for e.g., 106 * {@link org.apache.hadoop.hbase.client.coprocessor.LongColumnInterpreter}) then null should be 107 * returned. 108 * @return the PB message 109 */ 110 public abstract P getRequestData(); 111 112 /** 113 * This method should initialize any field(s) of the ColumnInterpreter with a parsing of the 114 * passed message bytes (used on the server side). n 115 */ 116 public abstract void initialize(P msg); 117 118 /** 119 * This method gets the PB message corresponding to the cell type n * @return the PB message for 120 * the cell-type instance 121 */ 122 public abstract Q getProtoForCellType(T t); 123 124 /** 125 * This method gets the PB message corresponding to the cell type n * @return the cell-type 126 * instance from the PB message 127 */ 128 public abstract T getCellValueFromProto(Q q); 129 130 /** 131 * This method gets the PB message corresponding to the promoted type n * @return the PB message 132 * for the promoted-type instance 133 */ 134 public abstract R getProtoForPromotedType(S s); 135 136 /** 137 * This method gets the promoted type from the proto message n * @return the promoted-type 138 * instance from the PB message 139 */ 140 public abstract S getPromotedValueFromProto(R r); 141 142 /** 143 * The response message comes as type S. This will convert/cast it to T. In some sense, performs 144 * the opposite of {@link #castToReturnType(Object)} nn 145 */ 146 public abstract T castToCellType(S response); 147}