View Javadoc

1   /**
2    * Copyright 2010 The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase.client;
21  
22  import org.apache.hadoop.conf.Configuration;
23  import org.apache.hadoop.hbase.HConstants;
24  import org.apache.hadoop.hbase.KeyValue;
25  import org.apache.hadoop.hbase.filter.Filter;
26  import org.apache.hadoop.hbase.io.TimeRange;
27  import org.apache.hadoop.hbase.util.Bytes;
28  import org.apache.hadoop.io.Writable;
29  import org.apache.hadoop.io.WritableFactories;
30  
31  import java.io.DataInput;
32  import java.io.DataOutput;
33  import java.io.IOException;
34  import java.util.ArrayList;
35  import java.util.HashMap;
36  import java.util.List;
37  import java.util.Map;
38  import java.util.NavigableSet;
39  import java.util.Set;
40  import java.util.TreeMap;
41  import java.util.TreeSet;
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 define the scope of what to get, perform additional methods as
48   * outlined below.
49   * <p>
50   * To get all columns from specific families, execute {@link #addFamily(byte[]) addFamily}
51   * for each family to retrieve.
52   * <p>
53   * To get specific columns, execute {@link #addColumn(byte[], byte[]) addColumn}
54   * for each column to retrieve.
55   * <p>
56   * To only retrieve columns within a specific range of version timestamps,
57   * execute {@link #setTimeRange(long, long) setTimeRange}.
58   * <p>
59   * To only retrieve columns with a specific timestamp, execute
60   * {@link #setTimeStamp(long) setTimestamp}.
61   * <p>
62   * To limit the number of versions of each column to be returned, execute
63   * {@link #setMaxVersions(int) setMaxVersions}.
64   * <p>
65   * To add a filter, execute {@link #setFilter(Filter) setFilter}.
66   */
67  public class Get extends OperationWithAttributes
68    implements Writable, Row, Comparable<Row> {
69    private static final byte GET_VERSION = (byte)2;
70  
71    private byte [] row = null;
72    private long lockId = -1L;
73    private int maxVersions = 1;
74    private boolean cacheBlocks = true;
75    private Filter filter = null;
76    private TimeRange tr = new TimeRange();
77    private Map<byte [], NavigableSet<byte []>> familyMap =
78      new TreeMap<byte [], NavigableSet<byte []>>(Bytes.BYTES_COMPARATOR);
79  
80    /** Constructor for Writable.  DO NOT USE */
81    public Get() {}
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      this(row, null);
92    }
93  
94    /**
95     * Create a Get operation for the specified row, using an existing row lock.
96     * <p>
97     * If no further operations are done, this will get the latest version of
98     * all columns in all families of the specified row.
99     * @param row row key
100    * @param rowLock previously acquired row lock, or null
101    * @deprecated {@link RowLock} is deprecated, use {@link #Get(byte[])}.
102    */
103   public Get(byte [] row, RowLock rowLock) {
104     this.row = row;
105     if(rowLock != null) {
106       this.lockId = rowLock.getLockId();
107     }
108   }
109 
110   /**
111    * Get all columns from the specified family.
112    * <p>
113    * Overrides previous calls to addColumn for this family.
114    * @param family family name
115    * @return the Get object
116    */
117   public Get addFamily(byte [] family) {
118     familyMap.remove(family);
119     familyMap.put(family, null);
120     return this;
121   }
122 
123   /**
124    * Get the column from the specific family with the specified qualifier.
125    * <p>
126    * Overrides previous calls to addFamily for this family.
127    * @param family family name
128    * @param qualifier column qualifier
129    * @return the Get objec
130    */
131   public Get addColumn(byte [] family, byte [] qualifier) {
132     NavigableSet<byte []> set = familyMap.get(family);
133     if(set == null) {
134       set = new TreeSet<byte []>(Bytes.BYTES_COMPARATOR);
135     }
136     if (qualifier == null) {
137       qualifier = HConstants.EMPTY_BYTE_ARRAY;
138     }
139     set.add(qualifier);
140     familyMap.put(family, set);
141     return this;
142   }
143 
144   /**
145    * Get versions of columns only within the specified timestamp range,
146    * [minStamp, maxStamp).
147    * @param minStamp minimum timestamp value, inclusive
148    * @param maxStamp maximum timestamp value, exclusive
149    * @throws IOException if invalid time range
150    * @return this for invocation chaining
151    */
152   public Get setTimeRange(long minStamp, long maxStamp)
153   throws IOException {
154     tr = new TimeRange(minStamp, maxStamp);
155     return this;
156   }
157 
158   /**
159    * Get versions of columns with the specified timestamp.
160    * @param timestamp version timestamp
161    * @return this for invocation chaining
162    */
163   public Get setTimeStamp(long timestamp) {
164     try {
165       tr = new TimeRange(timestamp, timestamp+1);
166     } catch(IOException e) {
167       // Will never happen
168     }
169     return this;
170   }
171 
172   /**
173    * Get all available versions.
174    * @return this for invocation chaining
175    */
176   public Get setMaxVersions() {
177     this.maxVersions = Integer.MAX_VALUE;
178     return this;
179   }
180 
181   /**
182    * Get up to the specified number of versions of each column.
183    * @param maxVersions maximum versions for each column
184    * @throws IOException if invalid number of versions
185    * @return this for invocation chaining
186    */
187   public Get setMaxVersions(int maxVersions) throws IOException {
188     if(maxVersions <= 0) {
189       throw new IOException("maxVersions must be positive");
190     }
191     this.maxVersions = maxVersions;
192     return this;
193   }
194 
195   /**
196    * Apply the specified server-side filter when performing the Get.
197    * Only {@link Filter#filterKeyValue(KeyValue)} is called AFTER all tests
198    * for ttl, column match, deletes and max versions have been run.
199    * @param filter filter to run on the server
200    * @return this for invocation chaining
201    */
202   public Get setFilter(Filter filter) {
203     this.filter = filter;
204     return this;
205   }
206 
207   /* Accessors */
208 
209   /**
210    * @return Filter
211    */
212   public Filter getFilter() {
213     return this.filter;
214   }
215 
216   /**
217    * Set whether blocks should be cached for this Get.
218    * <p>
219    * This is true by default.  When true, default settings of the table and
220    * family are used (this will never override caching blocks if the block
221    * cache is disabled for that family or entirely).
222    *
223    * @param cacheBlocks if false, default settings are overridden and blocks
224    * will not be cached
225    */
226   public void setCacheBlocks(boolean cacheBlocks) {
227     this.cacheBlocks = cacheBlocks;
228   }
229 
230   /**
231    * Get whether blocks should be cached for this Get.
232    * @return true if default caching should be used, false if blocks should not
233    * be cached
234    */
235   public boolean getCacheBlocks() {
236     return cacheBlocks;
237   }
238 
239   /**
240    * Method for retrieving the get's row
241    * @return row
242    */
243   public byte [] getRow() {
244     return this.row;
245   }
246 
247   /**
248    * Method for retrieving the get's RowLock
249    * @return RowLock
250    */
251   public RowLock getRowLock() {
252     return new RowLock(this.row, this.lockId);
253   }
254 
255   /**
256    * Method for retrieving the get's lockId
257    * @return lockId
258    */
259   public long getLockId() {
260     return this.lockId;
261   }
262 
263   /**
264    * Method for retrieving the get's maximum number of version
265    * @return the maximum number of version to fetch for this get
266    */
267   public int getMaxVersions() {
268     return this.maxVersions;
269   }
270 
271   /**
272    * Method for retrieving the get's TimeRange
273    * @return timeRange
274    */
275   public TimeRange getTimeRange() {
276     return this.tr;
277   }
278 
279   /**
280    * Method for retrieving the keys in the familyMap
281    * @return keys in the current familyMap
282    */
283   public Set<byte[]> familySet() {
284     return this.familyMap.keySet();
285   }
286 
287   /**
288    * Method for retrieving the number of families to get from
289    * @return number of families
290    */
291   public int numFamilies() {
292     return this.familyMap.size();
293   }
294 
295   /**
296    * Method for checking if any families have been inserted into this Get
297    * @return true if familyMap is non empty false otherwise
298    */
299   public boolean hasFamilies() {
300     return !this.familyMap.isEmpty();
301   }
302 
303   /**
304    * Method for retrieving the get's familyMap
305    * @return familyMap
306    */
307   public Map<byte[],NavigableSet<byte[]>> getFamilyMap() {
308     return this.familyMap;
309   }
310 
311   /**
312    * Compile the table and column family (i.e. schema) information
313    * into a String. Useful for parsing and aggregation by debugging,
314    * logging, and administration tools.
315    * @return Map
316    */
317   @Override
318   public Map<String, Object> getFingerprint() {
319     Map<String, Object> map = new HashMap<String, Object>();
320     List<String> families = new ArrayList<String>();
321     map.put("families", families);
322     for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
323       this.familyMap.entrySet()) {
324       families.add(Bytes.toStringBinary(entry.getKey()));
325     }
326     return map;
327   }
328 
329   /**
330    * Compile the details beyond the scope of getFingerprint (row, columns,
331    * timestamps, etc.) into a Map along with the fingerprinted information.
332    * Useful for debugging, logging, and administration tools.
333    * @param maxCols a limit on the number of columns output prior to truncation
334    * @return Map
335    */
336   @Override
337   public Map<String, Object> toMap(int maxCols) {
338     // we start with the fingerprint map and build on top of it.
339     Map<String, Object> map = getFingerprint();
340     // replace the fingerprint's simple list of families with a 
341     // map from column families to lists of qualifiers and kv details
342     Map<String, List<String>> columns = new HashMap<String, List<String>>();
343     map.put("families", columns);
344     // add scalar information first
345     map.put("row", Bytes.toStringBinary(this.row));
346     map.put("maxVersions", this.maxVersions);
347     map.put("cacheBlocks", this.cacheBlocks);
348     List<Long> timeRange = new ArrayList<Long>();
349     timeRange.add(this.tr.getMin());
350     timeRange.add(this.tr.getMax());
351     map.put("timeRange", timeRange);
352     int colCount = 0;
353     // iterate through affected families and add details
354     for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
355       this.familyMap.entrySet()) {
356       List<String> familyList = new ArrayList<String>();
357       columns.put(Bytes.toStringBinary(entry.getKey()), familyList);
358       if(entry.getValue() == null) {
359         colCount++;
360         --maxCols;
361         familyList.add("ALL");
362       } else {
363         colCount += entry.getValue().size();
364         if (maxCols <= 0) {
365           continue;
366         }
367         for (byte [] column : entry.getValue()) {
368           if (--maxCols <= 0) {
369             continue;
370           }
371           familyList.add(Bytes.toStringBinary(column));
372         }
373       }   
374     }   
375     map.put("totalColumns", colCount);
376     if (this.filter != null) {
377       map.put("filter", this.filter.toString());
378     }
379     // add the id if set
380     if (getId() != null) {
381       map.put("id", getId());
382     }
383     return map;
384   }
385 
386   //Row
387   public int compareTo(Row other) {
388     return Bytes.compareTo(this.getRow(), other.getRow());
389   }
390   
391   //Writable
392   public void readFields(final DataInput in)
393   throws IOException {
394     int version = in.readByte();
395     if (version > GET_VERSION) {
396       throw new IOException("unsupported version");
397     }
398     this.row = Bytes.readByteArray(in);
399     this.lockId = in.readLong();
400     this.maxVersions = in.readInt();
401     boolean hasFilter = in.readBoolean();
402     if (hasFilter) {
403       this.filter = (Filter)createForName(Bytes.toString(Bytes.readByteArray(in)));
404       this.filter.readFields(in);
405     }
406     this.cacheBlocks = in.readBoolean();
407     this.tr = new TimeRange();
408     tr.readFields(in);
409     int numFamilies = in.readInt();
410     this.familyMap =
411       new TreeMap<byte [],NavigableSet<byte []>>(Bytes.BYTES_COMPARATOR);
412     for(int i=0; i<numFamilies; i++) {
413       byte [] family = Bytes.readByteArray(in);
414       boolean hasColumns = in.readBoolean();
415       NavigableSet<byte []> set = null;
416       if(hasColumns) {
417         int numColumns = in.readInt();
418         set = new TreeSet<byte []>(Bytes.BYTES_COMPARATOR);
419         for(int j=0; j<numColumns; j++) {
420           byte [] qualifier = Bytes.readByteArray(in);
421           set.add(qualifier);
422         }
423       }
424       this.familyMap.put(family, set);
425     }
426     readAttributes(in);
427   }
428 
429   public void write(final DataOutput out)
430   throws IOException {
431     out.writeByte(GET_VERSION);
432     Bytes.writeByteArray(out, this.row);
433     out.writeLong(this.lockId);
434     out.writeInt(this.maxVersions);
435     if(this.filter == null) {
436       out.writeBoolean(false);
437     } else {
438       out.writeBoolean(true);
439       Bytes.writeByteArray(out, Bytes.toBytes(filter.getClass().getName()));
440       filter.write(out);
441     }
442     out.writeBoolean(this.cacheBlocks);
443     tr.write(out);
444     out.writeInt(familyMap.size());
445     for(Map.Entry<byte [], NavigableSet<byte []>> entry :
446       familyMap.entrySet()) {
447       Bytes.writeByteArray(out, entry.getKey());
448       NavigableSet<byte []> columnSet = entry.getValue();
449       if(columnSet == null) {
450         out.writeBoolean(false);
451       } else {
452         out.writeBoolean(true);
453         out.writeInt(columnSet.size());
454         for(byte [] qualifier : columnSet) {
455           Bytes.writeByteArray(out, qualifier);
456         }
457       }
458     }
459     writeAttributes(out);
460   }
461 
462   @SuppressWarnings("unchecked")
463   private Writable createForName(String className) {
464     try {
465       Class<? extends Writable> clazz =
466         (Class<? extends Writable>) Class.forName(className);
467       return WritableFactories.newInstance(clazz, new Configuration());
468     } catch (ClassNotFoundException e) {
469       throw new RuntimeException("Can't find class " + className);
470     }
471   }
472 }