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 &lt;T&gt;. 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 &lt;S&gt;. All computations are performed on the
038 * promoted data type &lt;S&gt;. There is a conversion method
039 * {@link ColumnInterpreter#castToReturnType(Object)} which takes a &lt;T&gt; type and returns a
040 * &lt;S&gt; type. The AggregateIm&gt;lementation uses PB messages to initialize the user's
041 * ColumnInterpreter implementation, and for sending the responses back to AggregationClient.
042 * <p>
043 * &lt;T&gt; Cell value data type<br>
044 * &lt;S&gt; Promoted data type<br>
045 * &lt;P&gt; PB message that is used to transport initializer specific bytes<br>
046 * &lt;Q&gt; PB message that is used to transport Cell (&lt;T&gt;) instance<br>
047 * &lt;R&gt; PB message that is used to transport Promoted (&lt;S&gt;) 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>&gt; 0 if l1 &gt; l2 or l1 is not null and l2 is null.</li>
091   * <li>&lt; 0 if l1 &lt; 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 &lt;S&gt; data values. Not providing the divide method that takes
098   * two &lt;S&gt; 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}