/
Mutation.java
456 lines (419 loc) · 15.5 KB
/
Mutation.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
/*
* Copyright 2017 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.cloud.spanner;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.base.Preconditions.checkState;
import com.google.common.collect.ImmutableList;
import com.google.protobuf.ListValue;
import java.io.Serializable;
import java.util.Collections;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import javax.annotation.Nullable;
/**
* Represents an individual table modification to be applied to Cloud Spanner.
*
* <p>The types of mutation that can be created are defined by {@link Op}. To construct a mutation,
* use one of the builder methods. For example, to create a mutation that will insert a value of "x"
* into "C1" and a value of "y" into "C2" of table "T", write the following code:
*
* <pre>
* Mutation m = Mutation.newInsertBuilder("T")
* .set("C1").to("x")
* .set("C2").to("y")
* .build();
* </pre>
*
* Mutations are applied to a database by performing a standalone write or buffering them as part of
* a transaction. TODO(user): Add links/code samples once the corresponding APIs are available.
*
* <p>{@code Mutation} instances are immutable.
*/
public final class Mutation implements Serializable {
private static final long serialVersionUID = 1784900828296918555L;
/** Enumerates the types of mutation that can be applied. */
public enum Op {
/**
* Inserts a new row in a table. If the row already exists, the write or transaction fails with
* {@link ErrorCode#ALREADY_EXISTS}. When inserting a row, all NOT NULL columns in the table
* must be given a value.
*/
INSERT,
/**
* Updates an existing row in a table. If the row does not already exist, the transaction fails
* with error {@link ErrorCode#NOT_FOUND}.
*/
UPDATE,
/**
* Like {@link #INSERT}, except that if the row already exists, then its column values are
* overwritten with the ones provided. All NOT NUll columns in the table must be give a value
* and this holds true even when the row already exists and will actually be updated. Values for
* all NULL columns not explicitly written are preserved.
*/
INSERT_OR_UPDATE,
/**
* Like {@link #INSERT}, except that if the row already exists, it is deleted, and the column
* values provided are inserted instead. Unlike {@link #INSERT_OR_UPDATE}, this means any values
* not explicitly written become {@code NULL}.
*/
REPLACE,
/** Deletes rows from a table. Succeeds whether or not the named rows were present. */
DELETE,
}
private final String table;
private final Op operation;
private final ImmutableList<String> columns;
private final ImmutableList<Value> values;
private final KeySet keySet;
private Mutation(
String table,
Op operation,
@Nullable ImmutableList<String> columns,
@Nullable ImmutableList<Value> values,
@Nullable KeySet keySet) {
this.table = table;
this.operation = operation;
this.columns = columns;
this.values = values;
this.keySet = keySet;
}
/**
* Returns a builder that can be used to construct an {@link Op#INSERT} mutation against {@code
* table}; see the {@code INSERT} documentation for mutation semantics.
*/
public static WriteBuilder newInsertBuilder(String table) {
return new WriteBuilder(table, Op.INSERT);
}
/**
* Returns a builder that can be used to construct an {@link Op#UPDATE} mutation against {@code
* table}; see the {@code UPDATE} documentation for mutation semantics.
*/
public static WriteBuilder newUpdateBuilder(String table) {
return new WriteBuilder(table, Op.UPDATE);
}
/**
* Returns a builder that can be used to construct an {@link Op#INSERT_OR_UPDATE} mutation against
* {@code table}; see the {@code INSERT_OR_UPDATE} documentation for mutation semantics.
*/
public static WriteBuilder newInsertOrUpdateBuilder(String table) {
return new WriteBuilder(table, Op.INSERT_OR_UPDATE);
}
/**
* Returns a builder that can be used to construct an {@link Op#REPLACE} mutation against {@code
* table}; see the {@code REPLACE} documentation for mutation semantics.
*/
public static WriteBuilder newReplaceBuilder(String table) {
return new WriteBuilder(table, Op.REPLACE);
}
/**
* Returns a mutation that will delete the row with primary key {@code key}. Exactly equivalent to
* {@code delete(table, KeySet.singleKey(key))}.
*/
public static Mutation delete(String table, Key key) {
return delete(table, KeySet.singleKey(key));
}
/** Returns a mutation that will delete all rows with primary keys covered by {@code keySet}. */
public static Mutation delete(String table, KeySet keySet) {
return new Mutation(table, Op.DELETE, null, null, checkNotNull(keySet));
}
/**
* Builder for {@link Op#INSERT}, {@link Op#INSERT_OR_UPDATE}, {@link Op#UPDATE}, and {@link
* Op#REPLACE} mutations.
*/
public static class WriteBuilder {
private final String table;
private final Op operation;
private final ImmutableList.Builder<String> columns;
private final ImmutableList.Builder<Value> values;
private final ValueBinder<WriteBuilder> binder;
private String currentColumn;
private WriteBuilder(String table, Op operation) {
this.table = checkNotNull(table);
this.operation = operation;
// Empty writes are sufficiently rare that it is not worth optimizing for that case.
this.columns = ImmutableList.builder();
this.values = ImmutableList.builder();
class BinderImpl extends ValueBinder<WriteBuilder> {
@Override
WriteBuilder handle(Value value) {
checkBindingInProgress(true);
columns.add(currentColumn);
values.add(value);
currentColumn = null;
return WriteBuilder.this;
}
}
this.binder = new BinderImpl();
}
/**
* Returns a binder to set the value of {@code columnName} that should be applied by the
* mutation.
*/
public ValueBinder<WriteBuilder> set(String columnName) {
checkBindingInProgress(false);
currentColumn = checkNotNull(columnName);
return binder;
}
/**
* Returns a newly created {@code Mutation} based on the contents of the {@code Builder}.
*
* @throws IllegalStateException if any duplicate columns are present. Duplicate detection is
* case-insensitive.
*/
public Mutation build() {
checkBindingInProgress(false);
ImmutableList<String> columnNames = columns.build();
checkDuplicateColumns(columnNames);
return new Mutation(table, operation, columnNames, values.build(), null);
}
private void checkBindingInProgress(boolean expectInProgress) {
if (expectInProgress) {
checkState(currentColumn != null, "No binding currently active");
} else if (currentColumn != null) {
throw new IllegalStateException("Incomplete binding for column " + currentColumn);
}
}
private void checkDuplicateColumns(ImmutableList<String> columnNames) {
Set<String> columnNameSet = new HashSet<>();
for (String columnName : columnNames) {
columnName = columnName.toLowerCase();
if (columnNameSet.contains(columnName)) {
throw new IllegalStateException("Duplicate column: " + columnName);
}
columnNameSet.add(columnName);
}
}
}
/** Returns the name of the table that this mutation will affect. */
public String getTable() {
return table;
}
/** Returns the type of operation that this mutation will perform. */
public Op getOperation() {
return operation;
}
/**
* For all types except {@link Op#DELETE}, returns the columns that this mutation will affect.
*
* @throws IllegalStateException if {@code operation() == Op.DELETE}
*/
public Iterable<String> getColumns() {
checkState(operation != Op.DELETE, "columns() cannot be called for a DELETE mutation");
return columns;
}
/**
* For all types except {@link Op#DELETE}, returns the values that this mutation will write. The
* number of elements returned is always the same as the number returned by {@link #getColumns()},
* and the {@code i}th value corresponds to the {@code i}th column.
*
* @throws IllegalStateException if {@code operation() == Op.DELETE}
*/
public Iterable<Value> getValues() {
checkState(operation != Op.DELETE, "values() cannot be called for a DELETE mutation");
return values;
}
/**
* For all types except {@link Op#DELETE}, constructs a map from column name to value. This is
* mainly intended as a convenience for testing; direct access via {@link #getColumns()} and
* {@link #getValues()} is more efficient.
*
* @throws IllegalStateException if {@code operation() == Op.DELETE}, or if any duplicate columns
* are present. Detection of duplicates does not consider case.
*/
public Map<String, Value> asMap() {
checkState(operation != Op.DELETE, "asMap() cannot be called for a DELETE mutation");
LinkedHashMap<String, Value> map = new LinkedHashMap<>();
for (int i = 0; i < columns.size(); ++i) {
Value existing = map.put(columns.get(i), values.get(i));
}
return Collections.unmodifiableMap(map);
}
/**
* For {@link Op#DELETE} mutations, returns the key set that defines the rows to be deleted.
*
* @throws IllegalStateException if {@code operation() != Op.DELETE}
*/
public KeySet getKeySet() {
checkState(operation == Op.DELETE, "keySet() can only be called for a DELETE mutation");
return keySet;
}
void toString(StringBuilder b) {
String opName;
boolean isWrite;
switch (operation) {
case INSERT:
opName = "insert";
isWrite = true;
break;
case INSERT_OR_UPDATE:
opName = "insert_or_update";
isWrite = true;
break;
case UPDATE:
opName = "update";
isWrite = true;
break;
case REPLACE:
opName = "replace";
isWrite = true;
break;
case DELETE:
opName = "delete";
isWrite = false;
break;
default:
throw new AssertionError("Unhandled Op: " + operation);
}
if (isWrite) {
b.append(opName).append('(').append(table).append('{');
for (int i = 0; i < columns.size(); ++i) {
if (i > 0) {
b.append(',');
}
b.append(columns.get(i));
b.append('=');
b.append(values.get(i));
}
b.append("})");
} else {
b.append("delete(").append(table);
keySet.toString(b);
b.append(')');
}
}
@Override
public String toString() {
StringBuilder b = new StringBuilder();
toString(b);
return b.toString();
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
Mutation that = (Mutation) o;
return operation == that.operation
&& Objects.equals(table, that.table)
&& Objects.equals(columns, that.columns)
&& areValuesEqual(values, that.values)
&& Objects.equals(keySet, that.keySet);
}
@Override
public int hashCode() {
return Objects.hash(operation, table, columns, values, keySet);
}
/**
* We are relaxing equality values here, making sure that Double.NaNs and Float.NaNs are equal to
* each other. This is because our Cloud Spanner Import / Export template in Apache Beam uses the
* mutation equality to check for modifications before committing. We noticed that when NaNs where
* used the template would always indicate a modification was present, when it turned out not to
* be the case. For more information see b/206339664.
*/
private boolean areValuesEqual(List<Value> values, List<Value> otherValues) {
if (values == null && otherValues == null) {
return true;
} else if (values == null || otherValues == null) {
return false;
} else if (values.size() != otherValues.size()) {
return false;
} else {
for (int i = 0; i < values.size(); i++) {
final Value value = values.get(i);
final Value otherValue = otherValues.get(i);
if (!value.equals(otherValue) && (!isNaN(value) || !isNaN(otherValue))) {
return false;
}
}
return true;
}
}
private boolean isNaN(Value value) {
return !value.isNull() && value.getType() == Type.float64() && Double.isNaN(value.getFloat64());
}
static void toProto(Iterable<Mutation> mutations, List<com.google.spanner.v1.Mutation> out) {
Mutation last = null;
// The mutation currently being built.
com.google.spanner.v1.Mutation.Builder proto = null;
// The "write" (!= DELETE) or "keySet" (==DELETE) for the last mutation encoded, for coalescing.
com.google.spanner.v1.Mutation.Write.Builder write = null;
com.google.spanner.v1.KeySet.Builder keySet = null;
for (Mutation mutation : mutations) {
if (mutation.operation == Op.DELETE) {
if (last != null && last.operation == Op.DELETE && mutation.table.equals(last.table)) {
mutation.keySet.appendToProto(keySet);
} else {
if (proto != null) {
out.add(proto.build());
}
proto = com.google.spanner.v1.Mutation.newBuilder();
com.google.spanner.v1.Mutation.Delete.Builder delete =
proto.getDeleteBuilder().setTable(mutation.table);
keySet = delete.getKeySetBuilder();
mutation.keySet.appendToProto(keySet);
}
write = null;
} else {
ListValue.Builder values = ListValue.newBuilder();
for (Value value : mutation.getValues()) {
values.addValues(value.toProto());
}
if (last != null
&& mutation.operation == last.operation
&& mutation.table.equals(last.table)
&& mutation.columns.equals(last.columns)) {
// Same as previous mutation: coalesce values to reduce request size.
write.addValues(values);
} else {
if (proto != null) {
out.add(proto.build());
}
proto = com.google.spanner.v1.Mutation.newBuilder();
switch (mutation.operation) {
case INSERT:
write = proto.getInsertBuilder();
break;
case UPDATE:
write = proto.getUpdateBuilder();
break;
case INSERT_OR_UPDATE:
write = proto.getInsertOrUpdateBuilder();
break;
case REPLACE:
write = proto.getReplaceBuilder();
break;
default:
throw new AssertionError("Impossible: " + mutation.operation);
}
write.setTable(mutation.table).addAllColumns(mutation.columns).addValues(values);
}
keySet = null;
}
last = mutation;
}
// Flush last item.
if (proto != null) {
out.add(proto.build());
}
}
}