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
23 import org.apache.hadoop.classification.InterfaceAudience;
24 import org.apache.hadoop.classification.InterfaceStability;
25 import org.apache.hadoop.hbase.Cell;
26 import org.apache.hadoop.hbase.KeyValue;
27 import org.apache.hadoop.hbase.KeyValueUtil;
28 import org.apache.hadoop.hbase.util.Bytes;
29
30 /**
31 * Performs Append operations on a single row.
32 * <p>
33 * Note that this operation does not appear atomic to readers. Appends are done
34 * under a single row lock, so write operations to a row are synchronized, but
35 * readers do not take row locks so get and scan operations can see this
36 * operation partially completed.
37 * <p>
38 * To append to a set of columns of a row, instantiate an Append object with the
39 * row to append to. At least one column to append must be specified using the
40 * {@link #add(byte[], byte[], byte[])} method.
41 */
42 @InterfaceAudience.Public
43 @InterfaceStability.Stable
44 public class Append extends Mutation {
45 private static final String RETURN_RESULTS = "_rr_";
46 /**
47 * @param returnResults
48 * True (default) if the append operation should return the results.
49 * A client that is not interested in the result can save network
50 * bandwidth setting this to false.
51 */
52 public void setReturnResults(boolean returnResults) {
53 setAttribute(RETURN_RESULTS, Bytes.toBytes(returnResults));
54 }
55
56 /**
57 * @return current setting for returnResults
58 */
59 public boolean isReturnResults() {
60 byte[] v = getAttribute(RETURN_RESULTS);
61 return v == null ? true : Bytes.toBoolean(v);
62 }
63
64 /**
65 * Create a Append operation for the specified row.
66 * <p>
67 * At least one column must be appended to.
68 * @param row row key; makes a local copy of passed in array.
69 */
70 public Append(byte[] row) {
71 this(row, 0, row.length);
72 }
73
74 /** Create a Append operation for the specified row.
75 * <p>
76 * At least one column must be appended to.
77 * @param rowArray Makes a copy out of this buffer.
78 * @param rowOffset
79 * @param rowLength
80 */
81 public Append(final byte [] rowArray, final int rowOffset, final int rowLength) {
82 checkRow(rowArray, rowOffset, rowLength);
83 this.row = Bytes.copy(rowArray, rowOffset, rowLength);
84 }
85
86 /**
87 * Add the specified column and value to this Append operation.
88 * @param family family name
89 * @param qualifier column qualifier
90 * @param value value to append to specified column
91 * @return this
92 */
93 public Append add(byte [] family, byte [] qualifier, byte [] value) {
94 KeyValue kv = new KeyValue(this.row, family, qualifier, this.ts, KeyValue.Type.Put, value);
95 return add(kv);
96 }
97
98 /**
99 * Add column and value to this Append operation.
100 * @param cell
101 * @return This instance
102 */
103 @SuppressWarnings("unchecked")
104 public Append add(final Cell cell) {
105 // Presume it is KeyValue for now.
106 KeyValue kv = KeyValueUtil.ensureKeyValue(cell);
107 byte [] family = kv.getFamily();
108 List<Cell> list = this.familyMap.get(family);
109 if (list == null) {
110 list = new ArrayList<Cell>();
111 }
112 // find where the new entry should be placed in the List
113 list.add(kv);
114 this.familyMap.put(family, list);
115 return this;
116 }
117 }