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