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  package org.apache.hadoop.hbase.client;
20  
21  
22  import java.io.IOException;
23  import java.util.ArrayList;
24  import java.util.HashMap;
25  import java.util.List;
26  import java.util.Map;
27  import java.util.NavigableSet;
28  import java.util.Set;
29  import java.util.TreeMap;
30  import java.util.TreeSet;
31  
32  import org.apache.commons.logging.Log;
33  import org.apache.commons.logging.LogFactory;
34  import org.apache.hadoop.classification.InterfaceAudience;
35  import org.apache.hadoop.classification.InterfaceStability;
36  import org.apache.hadoop.hbase.HConstants;
37  import org.apache.hadoop.hbase.filter.Filter;
38  import org.apache.hadoop.hbase.io.TimeRange;
39  import org.apache.hadoop.hbase.util.Bytes;
40  
41  /**
42   * Used to perform Get operations on a single row.
43   * <p>
44   * To get everything for a row, instantiate a Get object with the row to get.
45   * To further narrow the scope of what to Get, use the methods below.
46   * <p>
47   * To get all columns from specific families, execute {@link #addFamily(byte[]) addFamily}
48   * for each family to retrieve.
49   * <p>
50   * To get specific columns, execute {@link #addColumn(byte[], byte[]) addColumn}
51   * for each column to retrieve.
52   * <p>
53   * To only retrieve columns within a specific range of version timestamps,
54   * execute {@link #setTimeRange(long, long) setTimeRange}.
55   * <p>
56   * To only retrieve columns with a specific timestamp, execute
57   * {@link #setTimeStamp(long) setTimestamp}.
58   * <p>
59   * To limit the number of versions of each column to be returned, execute
60   * {@link #setMaxVersions(int) setMaxVersions}.
61   * <p>
62   * To add a filter, call {@link #setFilter(Filter) setFilter}.
63   */
64  @InterfaceAudience.Public
65  @InterfaceStability.Stable
66  public class Get extends Query
67    implements Row, Comparable<Row> {
68    private static final Log LOG = LogFactory.getLog(Get.class);
69  
70    private byte [] row = null;
71    private int maxVersions = 1;
72    private boolean cacheBlocks = true;
73    private int storeLimit = -1;
74    private int storeOffset = 0;
75    private TimeRange tr = new TimeRange();
76    private boolean checkExistenceOnly = false;
77    private boolean closestRowBefore = false;
78    private Map<byte [], NavigableSet<byte []>> familyMap =
79      new TreeMap<byte [], NavigableSet<byte []>>(Bytes.BYTES_COMPARATOR);
80  
81    /**
82     * Create a Get operation for the specified row.
83     * <p>
84     * If no further operations are done, this will get the latest version of
85     * all columns in all families of the specified row.
86     * @param row row key
87     */
88    public Get(byte [] row) {
89      Mutation.checkRow(row);
90      this.row = row;
91    }
92  
93    public boolean isCheckExistenceOnly() {
94      return checkExistenceOnly;
95    }
96  
97    public void setCheckExistenceOnly(boolean checkExistenceOnly) {
98      this.checkExistenceOnly = checkExistenceOnly;
99    }
100 
101   public boolean isClosestRowBefore() {
102     return closestRowBefore;
103   }
104 
105   public void setClosestRowBefore(boolean closestRowBefore) {
106     this.closestRowBefore = closestRowBefore;
107   }
108 
109   /**
110    * Get all columns from the specified family.
111    * <p>
112    * Overrides previous calls to addColumn for this family.
113    * @param family family name
114    * @return the Get object
115    */
116   public Get addFamily(byte [] family) {
117     familyMap.remove(family);
118     familyMap.put(family, null);
119     return this;
120   }
121 
122   /**
123    * Get the column from the specific family with the specified qualifier.
124    * <p>
125    * Overrides previous calls to addFamily for this family.
126    * @param family family name
127    * @param qualifier column qualifier
128    * @return the Get objec
129    */
130   public Get addColumn(byte [] family, byte [] qualifier) {
131     NavigableSet<byte []> set = familyMap.get(family);
132     if(set == null) {
133       set = new TreeSet<byte []>(Bytes.BYTES_COMPARATOR);
134     }
135     if (qualifier == null) {
136       qualifier = HConstants.EMPTY_BYTE_ARRAY;
137     }
138     set.add(qualifier);
139     familyMap.put(family, set);
140     return this;
141   }
142 
143   /**
144    * Get versions of columns only within the specified timestamp range,
145    * [minStamp, maxStamp).
146    * @param minStamp minimum timestamp value, inclusive
147    * @param maxStamp maximum timestamp value, exclusive
148    * @throws IOException if invalid time range
149    * @return this for invocation chaining
150    */
151   public Get setTimeRange(long minStamp, long maxStamp)
152   throws IOException {
153     tr = new TimeRange(minStamp, maxStamp);
154     return this;
155   }
156 
157   /**
158    * Get versions of columns with the specified timestamp.
159    * @param timestamp version timestamp
160    * @return this for invocation chaining
161    */
162   public Get setTimeStamp(long timestamp)
163   throws IOException {
164     try {
165       tr = new TimeRange(timestamp, timestamp+1);
166     } catch(IOException e) {
167       // This should never happen, unless integer overflow or something extremely wrong...
168       LOG.error("TimeRange failed, likely caused by integer overflow. ", e);
169       throw e;
170     }
171     return this;
172   }
173 
174   /**
175    * Get all available versions.
176    * @return this for invocation chaining
177    */
178   public Get setMaxVersions() {
179     this.maxVersions = Integer.MAX_VALUE;
180     return this;
181   }
182 
183   /**
184    * Get up to the specified number of versions of each column.
185    * @param maxVersions maximum versions for each column
186    * @throws IOException if invalid number of versions
187    * @return this for invocation chaining
188    */
189   public Get setMaxVersions(int maxVersions) throws IOException {
190     if(maxVersions <= 0) {
191       throw new IOException("maxVersions must be positive");
192     }
193     this.maxVersions = maxVersions;
194     return this;
195   }
196 
197   /**
198    * Set the maximum number of values to return per row per Column Family
199    * @param limit the maximum number of values returned / row / CF
200    * @return this for invocation chaining
201    */
202   public Get setMaxResultsPerColumnFamily(int limit) {
203     this.storeLimit = limit;
204     return this;
205   }
206 
207   /**
208    * Set offset for the row per Column Family. This offset is only within a particular row/CF
209    * combination. It gets reset back to zero when we move to the next row or CF.
210    * @param offset is the number of kvs that will be skipped.
211    * @return this for invocation chaining
212    */
213   public Get setRowOffsetPerColumnFamily(int offset) {
214     this.storeOffset = offset;
215     return this;
216   }
217 
218   @Override
219   public Get setFilter(Filter filter) {
220     super.setFilter(filter);
221     return this;
222   }
223 
224   /* Accessors */
225 
226   /**
227    * Set whether blocks should be cached for this Get.
228    * <p>
229    * This is true by default.  When true, default settings of the table and
230    * family are used (this will never override caching blocks if the block
231    * cache is disabled for that family or entirely).
232    *
233    * @param cacheBlocks if false, default settings are overridden and blocks
234    * will not be cached
235    */
236   public void setCacheBlocks(boolean cacheBlocks) {
237     this.cacheBlocks = cacheBlocks;
238   }
239 
240   /**
241    * Get whether blocks should be cached for this Get.
242    * @return true if default caching should be used, false if blocks should not
243    * be cached
244    */
245   public boolean getCacheBlocks() {
246     return cacheBlocks;
247   }
248 
249   /**
250    * Method for retrieving the get's row
251    * @return row
252    */
253   public byte [] getRow() {
254     return this.row;
255   }
256 
257   /**
258    * Method for retrieving the get's maximum number of version
259    * @return the maximum number of version to fetch for this get
260    */
261   public int getMaxVersions() {
262     return this.maxVersions;
263   }
264 
265   /**
266    * Method for retrieving the get's maximum number of values
267    * to return per Column Family
268    * @return the maximum number of values to fetch per CF
269    */
270   public int getMaxResultsPerColumnFamily() {
271     return this.storeLimit;
272   }
273 
274   /**
275    * Method for retrieving the get's offset per row per column
276    * family (#kvs to be skipped)
277    * @return the row offset
278    */
279   public int getRowOffsetPerColumnFamily() {
280     return this.storeOffset;
281   }
282 
283   /**
284    * Method for retrieving the get's TimeRange
285    * @return timeRange
286    */
287   public TimeRange getTimeRange() {
288     return this.tr;
289   }
290 
291   /**
292    * Method for retrieving the keys in the familyMap
293    * @return keys in the current familyMap
294    */
295   public Set<byte[]> familySet() {
296     return this.familyMap.keySet();
297   }
298 
299   /**
300    * Method for retrieving the number of families to get from
301    * @return number of families
302    */
303   public int numFamilies() {
304     return this.familyMap.size();
305   }
306 
307   /**
308    * Method for checking if any families have been inserted into this Get
309    * @return true if familyMap is non empty false otherwise
310    */
311   public boolean hasFamilies() {
312     return !this.familyMap.isEmpty();
313   }
314 
315   /**
316    * Method for retrieving the get's familyMap
317    * @return familyMap
318    */
319   public Map<byte[],NavigableSet<byte[]>> getFamilyMap() {
320     return this.familyMap;
321   }
322 
323   /**
324    * Compile the table and column family (i.e. schema) information
325    * into a String. Useful for parsing and aggregation by debugging,
326    * logging, and administration tools.
327    * @return Map
328    */
329   @Override
330   public Map<String, Object> getFingerprint() {
331     Map<String, Object> map = new HashMap<String, Object>();
332     List<String> families = new ArrayList<String>();
333     map.put("families", families);
334     for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
335       this.familyMap.entrySet()) {
336       families.add(Bytes.toStringBinary(entry.getKey()));
337     }
338     return map;
339   }
340 
341   /**
342    * Compile the details beyond the scope of getFingerprint (row, columns,
343    * timestamps, etc.) into a Map along with the fingerprinted information.
344    * Useful for debugging, logging, and administration tools.
345    * @param maxCols a limit on the number of columns output prior to truncation
346    * @return Map
347    */
348   @Override
349   public Map<String, Object> toMap(int maxCols) {
350     // we start with the fingerprint map and build on top of it.
351     Map<String, Object> map = getFingerprint();
352     // replace the fingerprint's simple list of families with a 
353     // map from column families to lists of qualifiers and kv details
354     Map<String, List<String>> columns = new HashMap<String, List<String>>();
355     map.put("families", columns);
356     // add scalar information first
357     map.put("row", Bytes.toStringBinary(this.row));
358     map.put("maxVersions", this.maxVersions);
359     map.put("cacheBlocks", this.cacheBlocks);
360     List<Long> timeRange = new ArrayList<Long>();
361     timeRange.add(this.tr.getMin());
362     timeRange.add(this.tr.getMax());
363     map.put("timeRange", timeRange);
364     int colCount = 0;
365     // iterate through affected families and add details
366     for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
367       this.familyMap.entrySet()) {
368       List<String> familyList = new ArrayList<String>();
369       columns.put(Bytes.toStringBinary(entry.getKey()), familyList);
370       if(entry.getValue() == null) {
371         colCount++;
372         --maxCols;
373         familyList.add("ALL");
374       } else {
375         colCount += entry.getValue().size();
376         if (maxCols <= 0) {
377           continue;
378         }
379         for (byte [] column : entry.getValue()) {
380           if (--maxCols <= 0) {
381             continue;
382           }
383           familyList.add(Bytes.toStringBinary(column));
384         }
385       }   
386     }   
387     map.put("totalColumns", colCount);
388     if (this.filter != null) {
389       map.put("filter", this.filter.toString());
390     }
391     // add the id if set
392     if (getId() != null) {
393       map.put("id", getId());
394     }
395     return map;
396   }
397 
398   //Row
399   @Override
400   public int compareTo(Row other) {
401     // TODO: This is wrong.  Can't have two gets the same just because on same row.
402     return Bytes.compareTo(this.getRow(), other.getRow());
403   }
404 
405   @Override
406   public int hashCode() {
407     // TODO: This is wrong.  Can't have two gets the same just because on same row.  But it
408     // matches how equals works currently and gets rid of the findbugs warning.
409     return Bytes.hashCode(this.getRow());
410   }
411 
412   @Override
413   public boolean equals(Object obj) {
414     if (this == obj) {
415       return true;
416     }
417     if (obj == null || getClass() != obj.getClass()) {
418       return false;
419     }
420     Row other = (Row) obj;
421     // TODO: This is wrong.  Can't have two gets the same just because on same row.
422     return compareTo(other) == 0;
423   }
424 }