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.classification.InterfaceAudience;
35  import org.apache.hadoop.hbase.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    /**
94     * Copy-constructor
95     *
96     * @param get
97     */
98    public Get(Get get) {
99      this(get.getRow());
100     this.filter = get.getFilter();
101     this.cacheBlocks = get.getCacheBlocks();
102     this.maxVersions = get.getMaxVersions();
103     this.storeLimit = get.getMaxResultsPerColumnFamily();
104     this.storeOffset = get.getRowOffsetPerColumnFamily();
105     this.tr = get.getTimeRange();
106     this.checkExistenceOnly = get.isCheckExistenceOnly();
107     this.closestRowBefore = get.isClosestRowBefore();
108     Map<byte[], NavigableSet<byte[]>> fams = get.getFamilyMap();
109     for (Map.Entry<byte[],NavigableSet<byte[]>> entry : fams.entrySet()) {
110       byte [] fam = entry.getKey();
111       NavigableSet<byte[]> cols = entry.getValue();
112       if (cols != null && cols.size() > 0) {
113         for (byte[] col : cols) {
114           addColumn(fam, col);
115         }
116       } else {
117         addFamily(fam);
118       }
119     }
120     for (Map.Entry<String, byte[]> attr : get.getAttributesMap().entrySet()) {
121       setAttribute(attr.getKey(), attr.getValue());
122     }
123   }
124 
125   public boolean isCheckExistenceOnly() {
126     return checkExistenceOnly;
127   }
128 
129   public void setCheckExistenceOnly(boolean checkExistenceOnly) {
130     this.checkExistenceOnly = checkExistenceOnly;
131   }
132 
133   public boolean isClosestRowBefore() {
134     return closestRowBefore;
135   }
136 
137   public void setClosestRowBefore(boolean closestRowBefore) {
138     this.closestRowBefore = closestRowBefore;
139   }
140 
141   /**
142    * Get all columns from the specified family.
143    * <p>
144    * Overrides previous calls to addColumn for this family.
145    * @param family family name
146    * @return the Get object
147    */
148   public Get addFamily(byte [] family) {
149     familyMap.remove(family);
150     familyMap.put(family, null);
151     return this;
152   }
153 
154   /**
155    * Get the column from the specific family with the specified qualifier.
156    * <p>
157    * Overrides previous calls to addFamily for this family.
158    * @param family family name
159    * @param qualifier column qualifier
160    * @return the Get objec
161    */
162   public Get addColumn(byte [] family, byte [] qualifier) {
163     NavigableSet<byte []> set = familyMap.get(family);
164     if(set == null) {
165       set = new TreeSet<byte []>(Bytes.BYTES_COMPARATOR);
166     }
167     if (qualifier == null) {
168       qualifier = HConstants.EMPTY_BYTE_ARRAY;
169     }
170     set.add(qualifier);
171     familyMap.put(family, set);
172     return this;
173   }
174 
175   /**
176    * Get versions of columns only within the specified timestamp range,
177    * [minStamp, maxStamp).
178    * @param minStamp minimum timestamp value, inclusive
179    * @param maxStamp maximum timestamp value, exclusive
180    * @throws IOException if invalid time range
181    * @return this for invocation chaining
182    */
183   public Get setTimeRange(long minStamp, long maxStamp)
184   throws IOException {
185     tr = new TimeRange(minStamp, maxStamp);
186     return this;
187   }
188 
189   /**
190    * Get versions of columns with the specified timestamp.
191    * @param timestamp version timestamp
192    * @return this for invocation chaining
193    */
194   public Get setTimeStamp(long timestamp)
195   throws IOException {
196     try {
197       tr = new TimeRange(timestamp, timestamp+1);
198     } catch(IOException e) {
199       // This should never happen, unless integer overflow or something extremely wrong...
200       LOG.error("TimeRange failed, likely caused by integer overflow. ", e);
201       throw e;
202     }
203     return this;
204   }
205 
206   /**
207    * Get all available versions.
208    * @return this for invocation chaining
209    */
210   public Get setMaxVersions() {
211     this.maxVersions = Integer.MAX_VALUE;
212     return this;
213   }
214 
215   /**
216    * Get up to the specified number of versions of each column.
217    * @param maxVersions maximum versions for each column
218    * @throws IOException if invalid number of versions
219    * @return this for invocation chaining
220    */
221   public Get setMaxVersions(int maxVersions) throws IOException {
222     if(maxVersions <= 0) {
223       throw new IOException("maxVersions must be positive");
224     }
225     this.maxVersions = maxVersions;
226     return this;
227   }
228 
229   /**
230    * Set the maximum number of values to return per row per Column Family
231    * @param limit the maximum number of values returned / row / CF
232    * @return this for invocation chaining
233    */
234   public Get setMaxResultsPerColumnFamily(int limit) {
235     this.storeLimit = limit;
236     return this;
237   }
238 
239   /**
240    * Set offset for the row per Column Family. This offset is only within a particular row/CF
241    * combination. It gets reset back to zero when we move to the next row or CF.
242    * @param offset is the number of kvs that will be skipped.
243    * @return this for invocation chaining
244    */
245   public Get setRowOffsetPerColumnFamily(int offset) {
246     this.storeOffset = offset;
247     return this;
248   }
249 
250   @Override
251   public Get setFilter(Filter filter) {
252     super.setFilter(filter);
253     return this;
254   }
255 
256   /* Accessors */
257 
258   /**
259    * Set whether blocks should be cached for this Get.
260    * <p>
261    * This is true by default.  When true, default settings of the table and
262    * family are used (this will never override caching blocks if the block
263    * cache is disabled for that family or entirely).
264    *
265    * @param cacheBlocks if false, default settings are overridden and blocks
266    * will not be cached
267    */
268   public void setCacheBlocks(boolean cacheBlocks) {
269     this.cacheBlocks = cacheBlocks;
270   }
271 
272   /**
273    * Get whether blocks should be cached for this Get.
274    * @return true if default caching should be used, false if blocks should not
275    * be cached
276    */
277   public boolean getCacheBlocks() {
278     return cacheBlocks;
279   }
280 
281   /**
282    * Method for retrieving the get's row
283    * @return row
284    */
285   public byte [] getRow() {
286     return this.row;
287   }
288 
289   /**
290    * Method for retrieving the get's maximum number of version
291    * @return the maximum number of version to fetch for this get
292    */
293   public int getMaxVersions() {
294     return this.maxVersions;
295   }
296 
297   /**
298    * Method for retrieving the get's maximum number of values
299    * to return per Column Family
300    * @return the maximum number of values to fetch per CF
301    */
302   public int getMaxResultsPerColumnFamily() {
303     return this.storeLimit;
304   }
305 
306   /**
307    * Method for retrieving the get's offset per row per column
308    * family (#kvs to be skipped)
309    * @return the row offset
310    */
311   public int getRowOffsetPerColumnFamily() {
312     return this.storeOffset;
313   }
314 
315   /**
316    * Method for retrieving the get's TimeRange
317    * @return timeRange
318    */
319   public TimeRange getTimeRange() {
320     return this.tr;
321   }
322 
323   /**
324    * Method for retrieving the keys in the familyMap
325    * @return keys in the current familyMap
326    */
327   public Set<byte[]> familySet() {
328     return this.familyMap.keySet();
329   }
330 
331   /**
332    * Method for retrieving the number of families to get from
333    * @return number of families
334    */
335   public int numFamilies() {
336     return this.familyMap.size();
337   }
338 
339   /**
340    * Method for checking if any families have been inserted into this Get
341    * @return true if familyMap is non empty false otherwise
342    */
343   public boolean hasFamilies() {
344     return !this.familyMap.isEmpty();
345   }
346 
347   /**
348    * Method for retrieving the get's familyMap
349    * @return familyMap
350    */
351   public Map<byte[],NavigableSet<byte[]>> getFamilyMap() {
352     return this.familyMap;
353   }
354 
355   /**
356    * Compile the table and column family (i.e. schema) information
357    * into a String. Useful for parsing and aggregation by debugging,
358    * logging, and administration tools.
359    * @return Map
360    */
361   @Override
362   public Map<String, Object> getFingerprint() {
363     Map<String, Object> map = new HashMap<String, Object>();
364     List<String> families = new ArrayList<String>();
365     map.put("families", families);
366     for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
367       this.familyMap.entrySet()) {
368       families.add(Bytes.toStringBinary(entry.getKey()));
369     }
370     return map;
371   }
372 
373   /**
374    * Compile the details beyond the scope of getFingerprint (row, columns,
375    * timestamps, etc.) into a Map along with the fingerprinted information.
376    * Useful for debugging, logging, and administration tools.
377    * @param maxCols a limit on the number of columns output prior to truncation
378    * @return Map
379    */
380   @Override
381   public Map<String, Object> toMap(int maxCols) {
382     // we start with the fingerprint map and build on top of it.
383     Map<String, Object> map = getFingerprint();
384     // replace the fingerprint's simple list of families with a
385     // map from column families to lists of qualifiers and kv details
386     Map<String, List<String>> columns = new HashMap<String, List<String>>();
387     map.put("families", columns);
388     // add scalar information first
389     map.put("row", Bytes.toStringBinary(this.row));
390     map.put("maxVersions", this.maxVersions);
391     map.put("cacheBlocks", this.cacheBlocks);
392     List<Long> timeRange = new ArrayList<Long>();
393     timeRange.add(this.tr.getMin());
394     timeRange.add(this.tr.getMax());
395     map.put("timeRange", timeRange);
396     int colCount = 0;
397     // iterate through affected families and add details
398     for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
399       this.familyMap.entrySet()) {
400       List<String> familyList = new ArrayList<String>();
401       columns.put(Bytes.toStringBinary(entry.getKey()), familyList);
402       if(entry.getValue() == null) {
403         colCount++;
404         --maxCols;
405         familyList.add("ALL");
406       } else {
407         colCount += entry.getValue().size();
408         if (maxCols <= 0) {
409           continue;
410         }
411         for (byte [] column : entry.getValue()) {
412           if (--maxCols <= 0) {
413             continue;
414           }
415           familyList.add(Bytes.toStringBinary(column));
416         }
417       }
418     }
419     map.put("totalColumns", colCount);
420     if (this.filter != null) {
421       map.put("filter", this.filter.toString());
422     }
423     // add the id if set
424     if (getId() != null) {
425       map.put("id", getId());
426     }
427     return map;
428   }
429 
430   //Row
431   @Override
432   public int compareTo(Row other) {
433     // TODO: This is wrong.  Can't have two gets the same just because on same row.
434     return Bytes.compareTo(this.getRow(), other.getRow());
435   }
436 
437   @Override
438   public int hashCode() {
439     // TODO: This is wrong.  Can't have two gets the same just because on same row.  But it
440     // matches how equals works currently and gets rid of the findbugs warning.
441     return Bytes.hashCode(this.getRow());
442   }
443 
444   @Override
445   public boolean equals(Object obj) {
446     if (this == obj) {
447       return true;
448     }
449     if (obj == null || getClass() != obj.getClass()) {
450       return false;
451     }
452     Row other = (Row) obj;
453     // TODO: This is wrong.  Can't have two gets the same just because on same row.
454     return compareTo(other) == 0;
455   }
456 }