hbase-client/src/main/java/org/apache/hadoop/hbase/client/Delete.java

   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.security.access.Permission;
  35 import org.apache.hadoop.hbase.security.visibility.CellVisibility;
  36 import org.apache.hadoop.hbase.util.Bytes;
  37
  38 /**
  39  * Used to perform Delete operations on a single row.
  40  * <p>
  41  * To delete an entire row, instantiate a Delete object with the row
  42  * to delete.  To further define the scope of what to delete, perform
  43  * additional methods as outlined below.
  44  * <p>
  45  * To delete specific families, execute {@link #addFamily(byte[]) deleteFamily}
  46  * for each family to delete.
  47  * <p>
  48  * To delete multiple versions of specific columns, execute
  49  * {@link #addColumns(byte[], byte[]) deleteColumns}
  50  * for each column to delete.
  51  * <p>
  52  * To delete specific versions of specific columns, execute
  53  * {@link #addColumn(byte[], byte[], long) deleteColumn}
  54  * for each column version to delete.
  55  * <p>
  56  * Specifying timestamps, deleteFamily and deleteColumns will delete all
  57  * versions with a timestamp less than or equal to that passed.  If no
  58  * timestamp is specified, an entry is added with a timestamp of 'now'
  59  * where 'now' is the servers's System.currentTimeMillis().
  60  * Specifying a timestamp to the deleteColumn method will
  61  * delete versions only with a timestamp equal to that specified.
  62  * If no timestamp is passed to deleteColumn, internally, it figures the
  63  * most recent cell's timestamp and adds a delete at that timestamp; i.e.
  64  * it deletes the most recently added cell.
  65  * <p>The timestamp passed to the constructor is used ONLY for delete of
  66  * rows.  For anything less -- a deleteColumn, deleteColumns or
  67  * deleteFamily -- then you need to use the method overrides that take a
  68  * timestamp.  The constructor timestamp is not referenced.
  69  */
  70 @InterfaceAudience.Public
  71 public class Delete extends Mutation implements Comparable<Row> {
  72   /**
  73    * Create a Delete operation for the specified row.
  74    * <p>
  75    * If no further operations are done, this will delete everything
  76    * associated with the specified row (all versions of all columns in all
  77    * families), with timestamp from current point in time to the past.
  78    * Cells defining timestamp for a future point in time
  79    * (timestamp > current time) will not be deleted.
  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 row We make a local copy of this passed in row.
 112    * @param rowOffset
 113    * @param rowLength
 114    */
 115   public Delete(final byte[] row, final int rowOffset, final int rowLength) {
 116     this(row, 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 row We make a local copy of this passed in row.
 129    * @param rowOffset
 130    * @param rowLength
 131    * @param timestamp maximum version timestamp (only for delete row)
 132    */
 133   public Delete(final byte[] row, final int rowOffset, final int rowLength, long timestamp) {
 134     checkRow(row, rowOffset, rowLength);
 135     this.row = Bytes.copy(row, rowOffset, rowLength);
 136     setTimestamp(timestamp);
 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 (!CellUtil.matchingRow(kv, this.row)) {
 167       throw new WrongRowIOException("The row in " + kv.toString() +
 168         " doesn't match the original one " +  Bytes.toStringBinary(this.row));
 169     }
 170     byte [] family = CellUtil.cloneFamily(kv);
 171     List<Cell> list = familyMap.get(family);
 172     if (list == null) {
 173       list = new ArrayList<>(1);
 174     }
 175     list.add(kv);
 176     familyMap.put(family, list);
 177     return this;
 178   }
 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 addFamily(final byte [] family) {
 190     this.addFamily(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   public Delete addFamily(final byte [] family, final long timestamp) {
 205     if (timestamp < 0) {
 206       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
 207     }
 208     List<Cell> list = familyMap.get(family);
 209     if(list == null) {
 210       list = new ArrayList<>(1);
 211     } else if(!list.isEmpty()) {
 212       list.clear();
 213     }
 214     KeyValue kv = new KeyValue(row, family, null, timestamp, KeyValue.Type.DeleteFamily);
 215     list.add(kv);
 216     familyMap.put(family, list);
 217     return this;
 218   }
 219
 220   /**
 221    * Delete all columns of the specified family with a timestamp equal to
 222    * the specified timestamp.
 223    * @param family family name
 224    * @param timestamp version timestamp
 225    * @return this for invocation chaining
 226    */
 227   public Delete addFamilyVersion(final byte [] family, final long timestamp) {
 228     List<Cell> list = familyMap.get(family);
 229     if(list == null) {
 230       list = new ArrayList<>(1);
 231     }
 232     list.add(new KeyValue(row, family, null, timestamp,
 233           KeyValue.Type.DeleteFamilyVersion));
 234     familyMap.put(family, list);
 235     return this;
 236   }
 237
 238   /**
 239    * Delete all versions of the specified column.
 240    * @param family family name
 241    * @param qualifier column qualifier
 242    * @return this for invocation chaining
 243    */
 244   public Delete addColumns(final byte [] family, final byte [] qualifier) {
 245     addColumns(family, qualifier, this.ts);
 246     return this;
 247   }
 248
 249   /**
 250    * Delete all versions of the specified column with a timestamp less than
 251    * or equal to the specified timestamp.
 252    * @param family family name
 253    * @param qualifier column qualifier
 254    * @param timestamp maximum version timestamp
 255    * @return this for invocation chaining
 256    */
 257   public Delete addColumns(final byte [] family, final byte [] qualifier, final long timestamp) {
 258     if (timestamp < 0) {
 259       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
 260     }
 261     List<Cell> list = familyMap.get(family);
 262     if (list == null) {
 263       list = new ArrayList<>(1);
 264     }
 265     list.add(new KeyValue(this.row, family, qualifier, timestamp,
 266         KeyValue.Type.DeleteColumn));
 267     familyMap.put(family, list);
 268     return this;
 269   }
 270
 271   /**
 272    * Delete the latest version of the specified column.
 273    * This is an expensive call in that on the server-side, it first does a
 274    * get to find the latest versions timestamp.  Then it adds a delete using
 275    * the fetched cells timestamp.
 276    * @param family family name
 277    * @param qualifier column qualifier
 278    * @return this for invocation chaining
 279    */
 280   public Delete addColumn(final byte [] family, final byte [] qualifier) {
 281     this.addColumn(family, qualifier, this.ts);
 282     return this;
 283   }
 284
 285   /**
 286    * Delete the specified version of the specified column.
 287    * @param family family name
 288    * @param qualifier column qualifier
 289    * @param timestamp version timestamp
 290    * @return this for invocation chaining
 291    */
 292   public Delete addColumn(byte [] family, byte [] qualifier, long timestamp) {
 293     if (timestamp < 0) {
 294       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
 295     }
 296     List<Cell> list = familyMap.get(family);
 297     if(list == null) {
 298       list = new ArrayList<>(1);
 299     }
 300     KeyValue kv = new KeyValue(this.row, family, qualifier, timestamp, KeyValue.Type.Delete);
 301     list.add(kv);
 302     familyMap.put(family, list);
 303     return this;
 304   }
 305
 306   /**
 307    * Set the timestamp of the delete.
 308    *
 309    * @param timestamp
 310    */
 311   public Delete setTimestamp(long timestamp) {
 312     if (timestamp < 0) {
 313       throw new IllegalArgumentException("Timestamp cannot be negative. ts=" + timestamp);
 314     }
 315     this.ts = timestamp;
 316     return this;
 317   }
 318
 319   @Override
 320   public Map<String, Object> toMap(int maxCols) {
 321     // we start with the fingerprint map and build on top of it.
 322     Map<String, Object> map = super.toMap(maxCols);
 323     // why is put not doing this?
 324     map.put("ts", this.ts);
 325     return map;
 326   }
 327
 328   @Override
 329   public Delete setAttribute(String name, byte[] value) {
 330     return (Delete) super.setAttribute(name, value);
 331   }
 332
 333   @Override
 334   public Delete setId(String id) {
 335     return (Delete) super.setId(id);
 336   }
 337
 338   @Override
 339   public Delete setDurability(Durability d) {
 340     return (Delete) super.setDurability(d);
 341   }
 342
 343   @Override
 344   public Delete setFamilyCellMap(NavigableMap<byte[], List<Cell>> map) {
 345     return (Delete) super.setFamilyCellMap(map);
 346   }
 347
 348   @Override
 349   public Delete setClusterIds(List<UUID> clusterIds) {
 350     return (Delete) super.setClusterIds(clusterIds);
 351   }
 352
 353   @Override
 354   public Delete setCellVisibility(CellVisibility expression) {
 355     return (Delete) super.setCellVisibility(expression);
 356   }
 357
 358   @Override
 359   public Delete setACL(String user, Permission perms) {
 360     return (Delete) super.setACL(user, perms);
 361   }
 362
 363   @Override
 364   public Delete setACL(Map<String, Permission> perms) {
 365     return (Delete) super.setACL(perms);
 366   }
 367
 368   @Override
 369   public Delete setTTL(long ttl) {
 370     throw new UnsupportedOperationException("Setting TTLs on Deletes is not supported");
 371   }
 372 }