View Javadoc

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