View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.hadoop.hbase.client;
19  
20  import java.util.ArrayList;
21  import java.util.List;
22  import java.util.Map;
23  
24  import org.apache.hadoop.classification.InterfaceAudience;
25  import org.apache.hadoop.classification.InterfaceStability;
26  import org.apache.hadoop.hbase.Cell;
27  import org.apache.hadoop.hbase.KeyValue;
28  import org.apache.hadoop.hbase.KeyValueUtil;
29  import org.apache.hadoop.hbase.util.Bytes;
30  
31  /**
32   * Performs Append operations on a single row.
33   * <p>
34   * Note that this operation does not appear atomic to readers. Appends are done
35   * under a single row lock, so write operations to a row are synchronized, but
36   * readers do not take row locks so get and scan operations can see this
37   * operation partially completed.
38   * <p>
39   * To append to a set of columns of a row, instantiate an Append object with the
40   * row to append to. At least one column to append must be specified using the
41   * {@link #add(byte[], byte[], byte[])} method.
42   */
43  @InterfaceAudience.Public
44  @InterfaceStability.Stable
45  public class Append extends Mutation {
46    private static final String RETURN_RESULTS = "_rr_";
47    /**
48     * @param returnResults
49     *          True (default) if the append operation should return the results.
50     *          A client that is not interested in the result can save network
51     *          bandwidth setting this to false.
52     */
53    public void setReturnResults(boolean returnResults) {
54      setAttribute(RETURN_RESULTS, Bytes.toBytes(returnResults));
55    }
56  
57    /**
58     * @return current setting for returnResults
59     */
60    public boolean isReturnResults() {
61      byte[] v = getAttribute(RETURN_RESULTS);
62      return v == null ? true : Bytes.toBoolean(v);
63    }
64  
65    /**
66     * Create a Append operation for the specified row.
67     * <p>
68     * At least one column must be appended to.
69     * @param row row key; makes a local copy of passed in array.
70     */
71    public Append(byte[] row) {
72      this(row, 0, row.length);
73    }
74    /**
75     * Copy constructor
76     * @param a
77     */
78    public Append(Append a) {
79      this.row = a.getRow();
80      this.ts = a.getTimeStamp();
81      this.familyMap.putAll(a.getFamilyCellMap());
82      for (Map.Entry<String, byte[]> entry : a.getAttributesMap().entrySet()) {
83        this.setAttribute(entry.getKey(), entry.getValue());
84      }
85    }
86  
87    /** Create a Append operation for the specified row.
88     * <p>
89     * At least one column must be appended to.
90     * @param rowArray Makes a copy out of this buffer.
91     * @param rowOffset
92     * @param rowLength
93     */
94    public Append(final byte [] rowArray, final int rowOffset, final int rowLength) {
95      checkRow(rowArray, rowOffset, rowLength);
96      this.row = Bytes.copy(rowArray, rowOffset, rowLength);
97    }
98  
99    /**
100    * Add the specified column and value to this Append operation.
101    * @param family family name
102    * @param qualifier column qualifier
103    * @param value value to append to specified column
104    * @return this
105    */
106   public Append add(byte [] family, byte [] qualifier, byte [] value) {
107     KeyValue kv = new KeyValue(this.row, family, qualifier, this.ts, KeyValue.Type.Put, value);
108     return add(kv);
109   }
110 
111   /**
112    * Add column and value to this Append operation.
113    * @param cell
114    * @return This instance
115    */
116   @SuppressWarnings("unchecked")
117   public Append add(final Cell cell) {
118     // Presume it is KeyValue for now.
119     KeyValue kv = KeyValueUtil.ensureKeyValue(cell);
120     byte [] family = kv.getFamily();
121     List<Cell> list = this.familyMap.get(family);
122     if (list == null) {
123       list  = new ArrayList<Cell>();
124     }
125     // find where the new entry should be placed in the List
126     list.add(kv);
127     this.familyMap.put(family, list);
128     return this;
129   }
130 }