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.util.ArrayList;
24  import java.util.List;
25  import java.util.Map;
26  import java.util.NavigableMap;
27  import java.util.UUID;
28  
29  import org.apache.hadoop.hbase.Cell;
30  import org.apache.hadoop.hbase.CellUtil;
31  import org.apache.hadoop.hbase.HConstants;
32  import org.apache.hadoop.hbase.KeyValue;
33  import org.apache.hadoop.hbase.classification.InterfaceAudience;
34  import org.apache.hadoop.hbase.classification.InterfaceStability;
35  import org.apache.hadoop.hbase.security.access.Permission;
36  import org.apache.hadoop.hbase.security.visibility.CellVisibility;
37  import org.apache.hadoop.hbase.util.Bytes;
38  
39  /**
40   * Used to perform Delete operations on a single row.
41   * <p>
42   * To delete an entire row, instantiate a Delete object with the row
43   * to delete.  To further define the scope of what to delete, perform
44   * additional methods as outlined below.
45   * <p>
46   * To delete specific families, execute {@link #deleteFamily(byte[]) deleteFamily}
47   * for each family to delete.
48   * <p>
49   * To delete multiple versions of specific columns, execute
50   * {@link #deleteColumns(byte[], byte[]) deleteColumns}
51   * for each column to delete.
52   * <p>
53   * To delete specific versions of specific columns, execute
54   * {@link #deleteColumn(byte[], byte[], long) deleteColumn}
55   * for each column version to delete.
56   * <p>
57   * Specifying timestamps, deleteFamily and deleteColumns will delete all
58   * versions with a timestamp less than or equal to that passed.  If no
59   * timestamp is specified, an entry is added with a timestamp of 'now'
60   * where 'now' is the servers's System.currentTimeMillis().
61   * Specifying a timestamp to the deleteColumn method will
62   * delete versions only with a timestamp equal to that specified.
63   * If no timestamp is passed to deleteColumn, internally, it figures the
64   * most recent cell's timestamp and adds a delete at that timestamp; i.e.
65   * it deletes the most recently added cell.
66   * <p>The timestamp passed to the constructor is used ONLY for delete of
67   * rows.  For anything less -- a deleteColumn, deleteColumns or
68   * deleteFamily -- then you need to use the method overrides that take a
69   * timestamp.  The constructor timestamp is not referenced.
70   */
71  @InterfaceAudience.Public
72  @InterfaceStability.Stable
73  public class Delete extends Mutation implements Comparable<Row> {
74    /**
75     * Create a Delete operation for the specified row.
76     * <p>
77     * If no further operations are done, this will delete everything
78     * associated with the specified row (all versions of all columns in all
79     * families).
80     * @param row row key
81     */
82    public Delete(byte [] row) {
83      this(row, HConstants.LATEST_TIMESTAMP);
84    }
85  
86    /**
87     * Create a Delete operation for the specified row and timestamp.<p>
88     *
89     * If no further operations are done, this will delete all columns in all
90     * families of the specified row with a timestamp less than or equal to the
91     * specified timestamp.<p>
92     *
93     * This timestamp is ONLY used for a delete row operation.  If specifying
94     * families or columns, you must specify each timestamp individually.
95     * @param row row key
96     * @param timestamp maximum version timestamp (only for delete row)
97     */
98    public Delete(byte [] row, long timestamp) {
99      this(row, 0, row.length, timestamp);
100   }
101 
102   /**
103    * Create a Delete operation for the specified row and timestamp.<p>
104    *
105    * If no further operations are done, this will delete all columns in all
106    * families of the specified row with a timestamp less than or equal to the
107    * specified timestamp.<p>
108    *
109    * This timestamp is ONLY used for a delete row operation.  If specifying
110    * families or columns, you must specify each timestamp individually.
111    * @param rowArray We make a local copy of this passed in row.
112    * @param rowOffset
113    * @param rowLength
114    */
115   public Delete(final byte [] rowArray, final int rowOffset, final int rowLength) {
116     this(rowArray, rowOffset, rowLength, HConstants.LATEST_TIMESTAMP);
117   }
118 
119   /**
120    * Create a Delete operation for the specified row and timestamp.<p>
121    *
122    * If no further operations are done, this will delete all columns in all
123    * families of the specified row with a timestamp less than or equal to the
124    * specified timestamp.<p>
125    *
126    * This timestamp is ONLY used for a delete row operation.  If specifying
127    * families or columns, you must specify each timestamp individually.
128    * @param rowArray We make a local copy of this passed in row.
129    * @param rowOffset
130    * @param rowLength
131    * @param ts maximum version timestamp (only for delete row)
132    */
133   public Delete(final byte [] rowArray, final int rowOffset, final int rowLength, long ts) {
134     checkRow(rowArray, rowOffset, rowLength);
135     this.row = Bytes.copy(rowArray, rowOffset, rowLength);
136     setTimestamp(ts);
137   }
138 
139   /**
140    * @param d Delete to clone.
141    */
142   public Delete(final Delete d) {
143     this.row = d.getRow();
144     this.ts = d.getTimeStamp();
145     this.familyMap.putAll(d.getFamilyCellMap());
146     this.durability = d.durability;
147     for (Map.Entry<String, byte[]> entry : d.getAttributesMap().entrySet()) {
148       this.setAttribute(entry.getKey(), entry.getValue());
149     }
150   }
151 
152   /**
153    * Advanced use only.
154    * Add an existing delete marker to this Delete object.
155    * @param kv An existing KeyValue of type "delete".
156    * @return this for invocation chaining
157    * @throws IOException
158    */
159   @SuppressWarnings("unchecked")
160   public Delete addDeleteMarker(Cell kv) throws IOException {
161     // TODO: Deprecate and rename 'add' so it matches how we add KVs to Puts.
162     if (!CellUtil.isDelete(kv)) {
163       throw new IOException("The recently added KeyValue is not of type "
164           + "delete. Rowkey: " + Bytes.toStringBinary(this.row));
165     }
166     if (Bytes.compareTo(this.row, 0, row.length, kv.getRowArray(),
167         kv.getRowOffset(), kv.getRowLength()) != 0) {
168       throw new WrongRowIOException("The row in " + kv.toString() +
169         " doesn't match the original one " +  Bytes.toStringBinary(this.row));
170     }
171     byte [] family = CellUtil.cloneFamily(kv);
172     List<Cell> list = familyMap.get(family);
173     if (list == null) {
174       list = new ArrayList<Cell>();
175     }
176     list.add(kv);
177     familyMap.put(family, list);
178     return this;
179   }
180 
181   /**
182    * Delete all versions of all columns of the specified family.
183    * <p>
184    * Overrides previous calls to deleteColumn and deleteColumns for the
185    * specified family.
186    * @param family family name
187    * @return this for invocation chaining
188    */
189   public Delete deleteFamily(byte [] family) {
190     this.deleteFamily(family, this.ts);
191     return this;
192   }
193 
194   /**
195    * Delete all columns of the specified family with a timestamp less than
196    * or equal to the specified timestamp.
197    * <p>
198    * Overrides previous calls to deleteColumn and deleteColumns for the
199    * specified family.
200    * @param family family name
201    * @param timestamp maximum version timestamp
202    * @return this for invocation chaining
203    */
204   @SuppressWarnings("unchecked")
205   public Delete deleteFamily(byte [] family, long timestamp) {
206     if (timestamp < 0) {
207       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
208     }
209     List<Cell> list = familyMap.get(family);
210     if(list == null) {
211       list = new ArrayList<Cell>();
212     } else if(!list.isEmpty()) {
213       list.clear();
214     }
215     KeyValue kv = new KeyValue(row, family, null, timestamp, KeyValue.Type.DeleteFamily);
216     list.add(kv);
217     familyMap.put(family, list);
218     return this;
219   }
220 
221   /**
222    * Delete all columns of the specified family with a timestamp equal to
223    * the specified timestamp.
224    * @param family family name
225    * @param timestamp version timestamp
226    * @return this for invocation chaining
227    */
228   public Delete deleteFamilyVersion(byte [] family, long timestamp) {
229     List<Cell> list = familyMap.get(family);
230     if(list == null) {
231       list = new ArrayList<Cell>();
232     }
233     list.add(new KeyValue(row, family, null, timestamp,
234           KeyValue.Type.DeleteFamilyVersion));
235     familyMap.put(family, list);
236     return this;
237   }
238 
239 
240   /**
241    * Delete all versions of the specified column.
242    * @param family family name
243    * @param qualifier column qualifier
244    * @return this for invocation chaining
245    */
246   public Delete deleteColumns(byte [] family, byte [] qualifier) {
247     this.deleteColumns(family, qualifier, this.ts);
248     return this;
249   }
250 
251   /**
252    * Delete all versions of the specified column with a timestamp less than
253    * or equal to the specified timestamp.
254    * @param family family name
255    * @param qualifier column qualifier
256    * @param timestamp maximum version timestamp
257    * @return this for invocation chaining
258    */
259   @SuppressWarnings("unchecked")
260   public Delete deleteColumns(byte [] family, byte [] qualifier, long timestamp) {
261     if (timestamp < 0) {
262       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
263     }
264     List<Cell> list = familyMap.get(family);
265     if (list == null) {
266       list = new ArrayList<Cell>();
267     }
268     list.add(new KeyValue(this.row, family, qualifier, timestamp,
269         KeyValue.Type.DeleteColumn));
270     familyMap.put(family, list);
271     return this;
272   }
273 
274   /**
275    * Delete the latest version of the specified column.
276    * This is an expensive call in that on the server-side, it first does a
277    * get to find the latest versions timestamp.  Then it adds a delete using
278    * the fetched cells timestamp.
279    * @param family family name
280    * @param qualifier column qualifier
281    * @return this for invocation chaining
282    */
283   public Delete deleteColumn(byte [] family, byte [] qualifier) {
284     this.deleteColumn(family, qualifier, this.ts);
285     return this;
286   }
287 
288   /**
289    * Delete the specified version of the specified column.
290    * @param family family name
291    * @param qualifier column qualifier
292    * @param timestamp version timestamp
293    * @return this for invocation chaining
294    */
295   @SuppressWarnings("unchecked")
296   public Delete deleteColumn(byte [] family, byte [] qualifier, long timestamp) {
297     if (timestamp < 0) {
298       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
299     }
300     List<Cell> list = familyMap.get(family);
301     if(list == null) {
302       list = new ArrayList<Cell>();
303     }
304     KeyValue kv = new KeyValue(this.row, family, qualifier, timestamp, KeyValue.Type.Delete);
305     list.add(kv);
306     familyMap.put(family, list);
307     return this;
308   }
309 
310   /**
311    * Set the timestamp of the delete.
312    *
313    * @param timestamp
314    */
315   public Delete setTimestamp(long timestamp) {
316     if (timestamp < 0) {
317       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
318     }
319     this.ts = timestamp;
320     return this;
321   }
322 
323   @Override
324   public Map<String, Object> toMap(int maxCols) {
325     // we start with the fingerprint map and build on top of it.
326     Map<String, Object> map = super.toMap(maxCols);
327     // why is put not doing this?
328     map.put("ts", this.ts);
329     return map;
330   }
331 
332   @Override
333   public Delete setAttribute(String name, byte[] value) {
334     return (Delete) super.setAttribute(name, value);
335   }
336 
337   @Override
338   public Delete setId(String id) {
339     return (Delete) super.setId(id);
340   }
341 
342   @Override
343   public Delete setDurability(Durability d) {
344     return (Delete) super.setDurability(d);
345   }
346 
347   @Override
348   public Delete setFamilyCellMap(NavigableMap<byte[], List<Cell>> map) {
349     return (Delete) super.setFamilyCellMap(map);
350   }
351 
352   @Override
353   public Delete setClusterIds(List<UUID> clusterIds) {
354     return (Delete) super.setClusterIds(clusterIds);
355   }
356 
357   @Override
358   public Delete setCellVisibility(CellVisibility expression) {
359     return (Delete) super.setCellVisibility(expression);
360   }
361 
362   @Override
363   public Delete setACL(String user, Permission perms) {
364     return (Delete) super.setACL(user, perms);
365   }
366 
367   @Override
368   public Delete setACL(Map<String, Permission> perms) {
369     return (Delete) super.setACL(perms);
370   }
371 }