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.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 }