Skip to content

Commit 8a123d9

Browse files
wu-huidlarocque
wu-hui
and
dlarocque
authored
feat(firestore): add support for BSON types (#13189)
Co-authored-by: dlarocque <daniellrq@outlook.com>
1 parent 2ce0744 commit 8a123d9

23 files changed

Lines changed: 3772 additions & 118 deletions

‎java-firestore/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Blob.java‎

Lines changed: 95 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,31 +27,89 @@ public final class Blob implements Serializable {
2727
private static final long serialVersionUID = 1441087101882481208L;
2828

2929
private final ByteString byteString;
30+
private final int subtype;
3031

31-
private Blob(ByteString byteString) {
32+
private Blob(ByteString byteString, int subtype) {
33+
if (subtype < 0 || subtype > 255) {
34+
throw new IllegalArgumentException(
35+
"The subtype for Blob must be a value in the inclusive [0, 255] range.");
36+
}
3237
this.byteString = byteString;
38+
this.subtype = subtype;
3339
}
3440

3541
/**
36-
* Creates a new Blob instance from the provided ByteString.
42+
* Creates a new Blob instance from the provided ByteString. Defaults to subtype 0 and native
43+
* representation.
3744
*
3845
* @param byteString The byteString to use for this Blob instance.
3946
* @return The new Blob instance
4047
*/
4148
@Nonnull
4249
public static Blob fromByteString(@Nonnull ByteString byteString) {
43-
return new Blob(byteString);
50+
return new Blob(byteString, 0);
4451
}
4552

4653
/**
4754
* Creates a new Blob instance from the provided bytes. Makes a copy of the bytes passed in.
55+
* Defaults to subtype 0 and native representation.
4856
*
4957
* @param bytes The bytes to use for this Blob instance.
5058
* @return The new Blob instance
5159
*/
5260
@Nonnull
5361
public static Blob fromBytes(@Nonnull byte[] bytes) {
54-
return new Blob(ByteString.copyFrom(bytes));
62+
return new Blob(ByteString.copyFrom(bytes), 0);
63+
}
64+
65+
/**
66+
* Creates a new Blob instance representing a BSON binary data type. Sets subtype to 0 and
67+
* representation to BSON.
68+
*
69+
* @param bytes The bytes to use for this Blob instance.
70+
* @return The new Blob instance
71+
*/
72+
@Nonnull
73+
public static Blob createBsonBinary(@Nonnull byte[] bytes) {
74+
return new Blob(ByteString.copyFrom(bytes), 0);
75+
}
76+
77+
/**
78+
* Creates a new Blob instance representing a BSON binary data type. Sets subtype to 0 and
79+
* representation to BSON.
80+
*
81+
* @param data The ByteString to use for this Blob instance.
82+
* @return The new Blob instance
83+
*/
84+
@Nonnull
85+
public static Blob createBsonBinary(@Nonnull ByteString data) {
86+
return new Blob(data, 0);
87+
}
88+
89+
/**
90+
* Creates a new Blob instance representing a BSON binary data type with a specific subtype. Sets
91+
* representation to BSON.
92+
*
93+
* @param subtype The subtype to use for this instance.
94+
* @param bytes The bytes to use for this Blob instance.
95+
* @return The new Blob instance
96+
*/
97+
@Nonnull
98+
public static Blob createBsonBinary(int subtype, @Nonnull byte[] bytes) {
99+
return new Blob(ByteString.copyFrom(bytes), subtype);
100+
}
101+
102+
/**
103+
* Creates a new Blob instance representing a BSON binary data type with a specific subtype. Sets
104+
* representation to BSON.
105+
*
106+
* @param subtype The subtype to use for this instance.
107+
* @param data The ByteString to use for this Blob instance.
108+
* @return The new Blob instance
109+
*/
110+
@Nonnull
111+
public static Blob createBsonBinary(int subtype, @Nonnull ByteString data) {
112+
return new Blob(data, subtype);
55113
}
56114

57115
/**
@@ -74,6 +132,16 @@ public byte[] toBytes() {
74132
return byteString.toByteArray();
75133
}
76134

135+
/**
136+
* Returns the subtype of this binary data. Defaults to 0 for both native binary and BSON binary
137+
* if not specified.
138+
*
139+
* @return The subtype of the binary data.
140+
*/
141+
public int subtype() {
142+
return this.subtype;
143+
}
144+
77145
/**
78146
* Returns true if this Blob is equal to the provided object.
79147
*
@@ -89,11 +157,32 @@ public boolean equals(Object obj) {
89157
return false;
90158
}
91159
Blob blob = (Blob) obj;
92-
return Objects.equals(byteString, blob.byteString);
160+
return this.subtype == blob.subtype && Objects.equals(byteString, blob.byteString);
93161
}
94162

95163
@Override
96164
public int hashCode() {
97-
return Objects.hash(byteString);
165+
return Objects.hash(byteString, subtype);
166+
}
167+
168+
@Nonnull
169+
@Override
170+
public String toString() {
171+
String dataStr;
172+
if (this.byteString.size() <= 100) {
173+
dataStr =
174+
com.google.common.io.BaseEncoding.base16()
175+
.lowerCase()
176+
.encode(this.byteString.toByteArray());
177+
} else {
178+
dataStr =
179+
com.google.common.io.BaseEncoding.base16()
180+
.lowerCase()
181+
.encode(this.byteString.substring(0, 20).toByteArray())
182+
+ "... (size="
183+
+ this.byteString.size()
184+
+ ")";
185+
}
186+
return "Blob{subtype=" + this.subtype + ", data=" + dataStr + "}";
98187
}
99188
}

‎java-firestore/google-cloud-firestore/src/main/java/com/google/cloud/firestore/BsonObjectId.java‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.firestore;
18+
19+
import com.google.firestore.v1.MapValue;
20+
import java.io.Serializable;
21+
import java.util.Objects;
22+
import javax.annotation.Nonnull;
23+
24+
/** Represents a BSON ObjectId type in Firestore documents. */
25+
public class BsonObjectId implements Serializable {
26+
private static final long serialVersionUID = 430753173775328933L;
27+
@Nonnull public final String value;
28+
29+
/**
30+
* Constructor that creates a new BSON ObjectId value with the given value.
31+
*
32+
* @param oid The 24-character hex string representing the ObjectId.
33+
*/
34+
public BsonObjectId(@Nonnull String oid) {
35+
this.value = oid;
36+
}
37+
38+
MapValue toProto() {
39+
return UserDataConverter.encodeBsonObjectId(value);
40+
}
41+
42+
/**
43+
* Returns true if this BsonObjectId is equal to the provided object.
44+
*
45+
* @param obj The object to compare against.
46+
* @return Whether this BsonObjectId is equal to the provided object.
47+
*/
48+
@Override
49+
public boolean equals(Object obj) {
50+
if (this == obj) {
51+
return true;
52+
}
53+
if (obj == null || getClass() != obj.getClass()) {
54+
return false;
55+
}
56+
BsonObjectId other = (BsonObjectId) obj;
57+
return Objects.equals(this.value, other.value);
58+
}
59+
60+
@Override
61+
public int hashCode() {
62+
return Objects.hash(this.value);
63+
}
64+
65+
@Nonnull
66+
@Override
67+
public String toString() {
68+
return "BsonObjectId{value=" + this.value + "}";
69+
}
70+
}

‎java-firestore/google-cloud-firestore/src/main/java/com/google/cloud/firestore/BsonTimestamp.java‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.firestore;
18+
19+
import com.google.firestore.v1.MapValue;
20+
import java.io.Serializable;
21+
import java.util.Objects;
22+
import javax.annotation.Nonnull;
23+
24+
/** Represents a BSON Timestamp type in Firestore documents. */
25+
public class BsonTimestamp implements Serializable {
26+
private static final long serialVersionUID = -1693962317170687337L;
27+
public final long seconds;
28+
public final long increment;
29+
30+
/**
31+
* Constructor that creates a new BSON Timestamp value with the given values.
32+
*
33+
* @param seconds An unsigned 32-bit integer value stored as long representing the seconds.
34+
* @param increment An unsigned 32-bit integer value stored as long representing the increment.
35+
*/
36+
public BsonTimestamp(long seconds, long increment) {
37+
if (seconds < 0 || seconds > 4294967295L) {
38+
throw new IllegalArgumentException(
39+
"BsonTimestamp 'seconds' must be in the range of a 32-bit unsigned integer.");
40+
}
41+
if (increment < 0 || increment > 4294967295L) {
42+
throw new IllegalArgumentException(
43+
"BsonTimestamp 'increment' must be in the range of a 32-bit unsigned integer.");
44+
}
45+
this.seconds = seconds;
46+
this.increment = increment;
47+
}
48+
49+
MapValue toProto() {
50+
return UserDataConverter.encodeBsonTimestamp(seconds, increment);
51+
}
52+
53+
/**
54+
* Returns true if this BsonTimestamp is equal to the provided object.
55+
*
56+
* @param obj The object to compare against.
57+
* @return Whether this BsonTimestamp is equal to the provided object.
58+
*/
59+
@Override
60+
public boolean equals(Object obj) {
61+
if (this == obj) {
62+
return true;
63+
}
64+
if (obj == null || getClass() != obj.getClass()) {
65+
return false;
66+
}
67+
BsonTimestamp other = (BsonTimestamp) obj;
68+
return this.seconds == other.seconds && this.increment == other.increment;
69+
}
70+
71+
@Override
72+
public int hashCode() {
73+
return Objects.hash(this.seconds, this.increment);
74+
}
75+
76+
@Nonnull
77+
@Override
78+
public String toString() {
79+
return "BsonTimestamp{seconds=" + this.seconds + ", increment=" + this.increment + "}";
80+
}
81+
}

‎java-firestore/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Decimal128Value.java‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.firestore;
18+
19+
import com.google.firestore.v1.MapValue;
20+
import java.io.Serializable;
21+
import java.util.Objects;
22+
import javax.annotation.Nonnull;
23+
24+
/** Represents a 128-bit decimal type in Firestore documents. */
25+
public class Decimal128Value implements Serializable {
26+
private static final long serialVersionUID = 8091951856970036899L;
27+
28+
public final String stringValue;
29+
final Quadruple value;
30+
31+
public Decimal128Value(String val) {
32+
this.stringValue = val;
33+
this.value = Quadruple.fromString(val);
34+
}
35+
36+
MapValue toProto() {
37+
return UserDataConverter.encodeDecimal128Value(stringValue);
38+
}
39+
40+
/**
41+
* Returns true if this Decimal128Value is equal to the provided object.
42+
*
43+
* @param obj The object to compare against.
44+
* @return Whether this Decimal128Value is equal to the provided object.
45+
*/
46+
@Override
47+
public boolean equals(Object obj) {
48+
if (obj == null || getClass() != obj.getClass()) {
49+
return false;
50+
}
51+
52+
Quadruple lhs = this.value;
53+
Quadruple rhs = ((Decimal128Value) obj).value;
54+
55+
// Firestore considers +0 and -0 to be equal, but `Quadruple.compareTo()` does not.
56+
if (lhs.isZero() && rhs.isZero()) return true;
57+
58+
return this == obj || lhs.compareTo(rhs) == 0;
59+
}
60+
61+
@Override
62+
public int hashCode() {
63+
// Since +0 and -0 are considered equal, they should have the same hash code.
64+
Quadruple quadruple =
65+
(this.value.compareTo(Quadruple.NEGATIVE_ZERO) == 0) ? Quadruple.POSITIVE_ZERO : this.value;
66+
67+
return Objects.hash(quadruple);
68+
}
69+
70+
@Nonnull
71+
@Override
72+
public String toString() {
73+
return "Decimal128Value{value=" + this.stringValue + "}";
74+
}
75+
}

0 commit comments

Comments
 (0)