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.client;
21  
22  import java.io.IOException;
23  import java.nio.ByteBuffer;
24  import java.util.ArrayList;
25  import java.util.List;
26  import java.util.Map;
27  import java.util.NavigableMap;
28  import java.util.TreeMap;
29  import java.util.UUID;
30  
31  import org.apache.hadoop.hbase.Cell;
32  import org.apache.hadoop.hbase.CellUtil;
33  import org.apache.hadoop.hbase.HConstants;
34  import org.apache.hadoop.hbase.KeyValue;
35  import org.apache.hadoop.hbase.Tag;
36  import org.apache.hadoop.hbase.classification.InterfaceAudience;
37  import org.apache.hadoop.hbase.classification.InterfaceStability;
38  import org.apache.hadoop.hbase.io.HeapSize;
39  import org.apache.hadoop.hbase.security.access.Permission;
40  import org.apache.hadoop.hbase.security.visibility.CellVisibility;
41  import org.apache.hadoop.hbase.util.Bytes;
42  
43  /**
44   * Used to perform Put operations for a single row.
45   * <p>
46   * To perform a Put, instantiate a Put object with the row to insert to and
47   * for eachumn to be inserted, execute {@link #add(byte[], byte[], byte[]) add} or
48   * {@link #add(byte[], byte[], long, byte[]) add} if setting the timestamp.
49   */
50  @InterfaceAudience.Public
51  @InterfaceStability.Stable
52  public class Put extends Mutation implements HeapSize, Comparable<Row> {
53    /**
54     * Create a Put operation for the specified row.
55     * @param row row key
56     */
57    public Put(byte [] row) {
58      this(row, HConstants.LATEST_TIMESTAMP);
59    }
60  
61    /**
62     * Create a Put operation for the specified row, using a given timestamp.
63     *
64     * @param row row key; we make a copy of what we are passed to keep local.
65     * @param ts timestamp
66     */
67    public Put(byte[] row, long ts) {
68      this(row, 0, row.length, ts);
69    }
70  
71    /**
72     * We make a copy of the passed in row key to keep local.
73     * @param rowArray
74     * @param rowOffset
75     * @param rowLength
76     */
77    public Put(byte [] rowArray, int rowOffset, int rowLength) {
78      this(rowArray, rowOffset, rowLength, HConstants.LATEST_TIMESTAMP);
79    }
80  
81    /**
82     * @param row row key; we make a copy of what we are passed to keep local.
83     * @param ts  timestamp
84     */
85    public Put(ByteBuffer row, long ts) {
86      if (ts < 0) {
87        throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
88      }
89      checkRow(row);
90      this.row = new byte[row.remaining()];
91      row.get(this.row);
92      this.ts = ts;
93    }
94  
95    /**
96     * @param row row key; we make a copy of what we are passed to keep local.
97     */
98    public Put(ByteBuffer row) {
99      this(row, HConstants.LATEST_TIMESTAMP);
100   }
101 
102   /**
103    * We make a copy of the passed in row key to keep local.
104    * @param rowArray
105    * @param rowOffset
106    * @param rowLength
107    * @param ts
108    */
109   public Put(byte [] rowArray, int rowOffset, int rowLength, long ts) {
110     checkRow(rowArray, rowOffset, rowLength);
111     this.row = Bytes.copy(rowArray, rowOffset, rowLength);
112     this.ts = ts;
113     if (ts < 0) {
114       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
115     }
116   }
117 
118   /**
119    * Copy constructor.  Creates a Put operation cloned from the specified Put.
120    * @param putToCopy put to copy
121    */
122   public Put(Put putToCopy) {
123     this(putToCopy.getRow(), putToCopy.ts);
124     this.familyMap = new TreeMap<byte [], List<Cell>>(Bytes.BYTES_COMPARATOR);
125     for(Map.Entry<byte [], List<Cell>> entry: putToCopy.getFamilyCellMap().entrySet()) {
126       this.familyMap.put(entry.getKey(), entry.getValue());
127     }
128     this.durability = putToCopy.durability;
129     for (Map.Entry<String, byte[]> entry : putToCopy.getAttributesMap().entrySet()) {
130       this.setAttribute(entry.getKey(), entry.getValue());
131     }
132   }
133 
134   /**
135    * Add the specified column and value to this Put operation.
136    * @param family family name
137    * @param qualifier column qualifier
138    * @param value column value
139    * @return this
140    */
141   public Put add(byte [] family, byte [] qualifier, byte [] value) {
142     return add(family, qualifier, this.ts, value);
143   }
144 
145   /**
146    * See {@link #add(byte[], byte[], byte[])}. This version expects
147    * that the underlying arrays won't change. It's intended
148    * for usage internal HBase to and for advanced client applications.
149    */
150   public Put addImmutable(byte [] family, byte [] qualifier, byte [] value) {
151     return addImmutable(family, qualifier, this.ts, value);
152   }
153 
154   /**
155    * This expects that the underlying arrays won't change. It's intended
156    * for usage internal HBase to and for advanced client applications.
157    */
158   public Put addImmutable(byte[] family, byte [] qualifier, byte [] value, Tag[] tag) {
159     return addImmutable(family, qualifier, this.ts, value, tag);
160   }
161 
162   /**
163    * Add the specified column and value, with the specified timestamp as
164    * its version to this Put operation.
165    * @param family family name
166    * @param qualifier column qualifier
167    * @param ts version timestamp
168    * @param value column value
169    * @return this
170    */
171   public Put add(byte [] family, byte [] qualifier, long ts, byte [] value) {
172     if (ts < 0) {
173       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
174     }
175     List<Cell> list = getCellList(family);
176     KeyValue kv = createPutKeyValue(family, qualifier, ts, value);
177     list.add(kv);
178     familyMap.put(CellUtil.cloneFamily(kv), list);
179     return this;
180   }
181 
182   /**
183    * See {@link #add(byte[], byte[], long, byte[])}. This version expects
184    * that the underlying arrays won't change. It's intended
185    * for usage internal HBase to and for advanced client applications.
186    */
187   public Put addImmutable(byte [] family, byte [] qualifier, long ts, byte [] value) {
188     if (ts < 0) {
189       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
190     }
191     List<Cell> list = getCellList(family);
192     KeyValue kv = createPutKeyValue(family, qualifier, ts, value);
193     list.add(kv);
194     familyMap.put(family, list);
195     return this;
196   }
197 
198   /**
199    * This expects that the underlying arrays won't change. It's intended
200    * for usage internal HBase to and for advanced client applications.
201    */
202   @SuppressWarnings("unchecked")
203   public Put addImmutable(byte[] family, byte[] qualifier, long ts, byte[] value, Tag[] tag) {
204     List<Cell> list = getCellList(family);
205     KeyValue kv = createPutKeyValue(family, qualifier, ts, value, tag);
206     list.add(kv);
207     familyMap.put(family, list);
208     return this;
209   }
210 
211   /**
212    * This expects that the underlying arrays won't change. It's intended
213    * for usage internal HBase to and for advanced client applications.
214    */
215   public Put addImmutable(byte[] family, ByteBuffer qualifier, long ts, ByteBuffer value,
216                           Tag[] tag) {
217     if (ts < 0) {
218       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
219     }
220     List<Cell> list = getCellList(family);
221     KeyValue kv = createPutKeyValue(family, qualifier, ts, value, tag);
222     list.add(kv);
223     familyMap.put(family, list);
224     return this;
225   }
226 
227 
228   /**
229    * Add the specified column and value, with the specified timestamp as
230    * its version to this Put operation.
231    * @param family family name
232    * @param qualifier column qualifier
233    * @param ts version timestamp
234    * @param value column value
235    * @return this
236    */
237   public Put add(byte[] family, ByteBuffer qualifier, long ts, ByteBuffer value) {
238     if (ts < 0) {
239       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
240     }
241     List<Cell> list = getCellList(family);
242     KeyValue kv = createPutKeyValue(family, qualifier, ts, value, null);
243     list.add(kv);
244     familyMap.put(CellUtil.cloneFamily(kv), list);
245     return this;
246   }
247 
248   /**
249    * See {@link #add(byte[], ByteBuffer, long, ByteBuffer)}. This version expects
250    * that the underlying arrays won't change. It's intended
251    * for usage internal HBase to and for advanced client applications.
252    */
253   public Put addImmutable(byte[] family, ByteBuffer qualifier, long ts, ByteBuffer value) {
254     if (ts < 0) {
255       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + ts);
256     }
257     List<Cell> list = getCellList(family);
258     KeyValue kv = createPutKeyValue(family, qualifier, ts, value, null);
259     list.add(kv);
260     familyMap.put(family, list);
261     return this;
262   }
263 
264   /**
265    * Add the specified KeyValue to this Put operation.  Operation assumes that
266    * the passed KeyValue is immutable and its backing array will not be modified
267    * for the duration of this Put.
268    * @param kv individual KeyValue
269    * @return this
270    * @throws java.io.IOException e
271    */
272   public Put add(Cell kv) throws IOException{
273     byte [] family = CellUtil.cloneFamily(kv);
274     List<Cell> list = getCellList(family);
275     //Checking that the row of the kv is the same as the put
276     int res = Bytes.compareTo(this.row, 0, row.length,
277         kv.getRowArray(), kv.getRowOffset(), kv.getRowLength());
278     if (res != 0) {
279       throw new WrongRowIOException("The row in " + kv.toString() +
280         " doesn't match the original one " +  Bytes.toStringBinary(this.row));
281     }
282     list.add(kv);
283     familyMap.put(family, list);
284     return this;
285   }
286 
287   /**
288    * A convenience method to determine if this object's familyMap contains
289    * a value assigned to the given family & qualifier.
290    * Both given arguments must match the KeyValue object to return true.
291    *
292    * @param family column family
293    * @param qualifier column qualifier
294    * @return returns true if the given family and qualifier already has an
295    * existing KeyValue object in the family map.
296    */
297   public boolean has(byte [] family, byte [] qualifier) {
298   return has(family, qualifier, this.ts, new byte[0], true, true);
299   }
300 
301   /**
302    * A convenience method to determine if this object's familyMap contains
303    * a value assigned to the given family, qualifier and timestamp.
304    * All 3 given arguments must match the KeyValue object to return true.
305    *
306    * @param family column family
307    * @param qualifier column qualifier
308    * @param ts timestamp
309    * @return returns true if the given family, qualifier and timestamp already has an
310    * existing KeyValue object in the family map.
311    */
312   public boolean has(byte [] family, byte [] qualifier, long ts) {
313   return has(family, qualifier, ts, new byte[0], false, true);
314   }
315 
316   /**
317    * A convenience method to determine if this object's familyMap contains
318    * a value assigned to the given family, qualifier and timestamp.
319    * All 3 given arguments must match the KeyValue object to return true.
320    *
321    * @param family column family
322    * @param qualifier column qualifier
323    * @param value value to check
324    * @return returns true if the given family, qualifier and value already has an
325    * existing KeyValue object in the family map.
326    */
327   public boolean has(byte [] family, byte [] qualifier, byte [] value) {
328     return has(family, qualifier, this.ts, value, true, false);
329   }
330 
331   /**
332    * A convenience method to determine if this object's familyMap contains
333    * the given value assigned to the given family, qualifier and timestamp.
334    * All 4 given arguments must match the KeyValue object to return true.
335    *
336    * @param family column family
337    * @param qualifier column qualifier
338    * @param ts timestamp
339    * @param value value to check
340    * @return returns true if the given family, qualifier timestamp and value
341    * already has an existing KeyValue object in the family map.
342    */
343   public boolean has(byte [] family, byte [] qualifier, long ts, byte [] value) {
344       return has(family, qualifier, ts, value, false, false);
345   }
346 
347   /*
348    * Private method to determine if this object's familyMap contains
349    * the given value assigned to the given family, qualifier and timestamp
350    * respecting the 2 boolean arguments
351    *
352    * @param family
353    * @param qualifier
354    * @param ts
355    * @param value
356    * @param ignoreTS
357    * @param ignoreValue
358    * @return returns true if the given family, qualifier timestamp and value
359    * already has an existing KeyValue object in the family map.
360    */
361   private boolean has(byte[] family, byte[] qualifier, long ts, byte[] value,
362                       boolean ignoreTS, boolean ignoreValue) {
363     List<Cell> list = getCellList(family);
364     if (list.size() == 0) {
365       return false;
366     }
367     // Boolean analysis of ignoreTS/ignoreValue.
368     // T T => 2
369     // T F => 3 (first is always true)
370     // F T => 2
371     // F F => 1
372     if (!ignoreTS && !ignoreValue) {
373       for (Cell cell : list) {
374         if (CellUtil.matchingFamily(cell, family) &&
375             CellUtil.matchingQualifier(cell, qualifier)  &&
376             CellUtil.matchingValue(cell, value) &&
377             cell.getTimestamp() == ts) {
378           return true;
379         }
380       }
381     } else if (ignoreValue && !ignoreTS) {
382       for (Cell cell : list) {
383         if (CellUtil.matchingFamily(cell, family) && CellUtil.matchingQualifier(cell, qualifier)
384             && cell.getTimestamp() == ts) {
385           return true;
386         }
387       }
388     } else if (!ignoreValue && ignoreTS) {
389       for (Cell cell : list) {
390         if (CellUtil.matchingFamily(cell, family) && CellUtil.matchingQualifier(cell, qualifier)
391             && CellUtil.matchingValue(cell, value)) {
392           return true;
393         }
394       }
395     } else {
396       for (Cell cell : list) {
397         if (CellUtil.matchingFamily(cell, family) &&
398             CellUtil.matchingQualifier(cell, qualifier)) {
399           return true;
400         }
401       }
402     }
403     return false;
404   }
405 
406   /**
407    * Returns a list of all KeyValue objects with matching column family and qualifier.
408    *
409    * @param family column family
410    * @param qualifier column qualifier
411    * @return a list of KeyValue objects with the matching family and qualifier,
412    * returns an empty list if one doesn't exist for the given family.
413    */
414   public List<Cell> get(byte[] family, byte[] qualifier) {
415     List<Cell> filteredList = new ArrayList<Cell>();
416     for (Cell cell: getCellList(family)) {
417       if (CellUtil.matchingQualifier(cell, qualifier)) {
418         filteredList.add(cell);
419       }
420     }
421     return filteredList;
422   }
423 
424   @Override
425   public Put setAttribute(String name, byte[] value) {
426     return (Put) super.setAttribute(name, value);
427   }
428 
429   @Override
430   public Put setId(String id) {
431     return (Put) super.setId(id);
432   }
433 
434   @Override
435   public Put setDurability(Durability d) {
436     return (Put) super.setDurability(d);
437   }
438 
439   @Override
440   public Put setFamilyCellMap(NavigableMap<byte[], List<Cell>> map) {
441     return (Put) super.setFamilyCellMap(map);
442   }
443 
444   @Override
445   public Put setClusterIds(List<UUID> clusterIds) {
446     return (Put) super.setClusterIds(clusterIds);
447   }
448 
449   @Override
450   public Put setCellVisibility(CellVisibility expression) {
451     return (Put) super.setCellVisibility(expression);
452   }
453 
454   @Override
455   public Put setACL(String user, Permission perms) {
456     return (Put) super.setACL(user, perms);
457   }
458 
459   @Override
460   public Put setACL(Map<String, Permission> perms) {
461     return (Put) super.setACL(perms);
462   }
463 }