serviceAccountScopes)
+ throws GeneralSecurityException, IOException {
+ HttpTransport transport = newTransport();
+ JsonFactory jsonFactory = newJsonFactory();
+ return new GoogleCredential.Builder()
+ .setTransport(transport)
+ .setJsonFactory(jsonFactory)
+ .setServiceAccountId(serviceAccountId)
+ .setServiceAccountScopes(serviceAccountScopes);
+ }
+
+ /**
+ * Constructs a {@link Datastore} from environment variables and/or the Compute Engine metadata
+ * server.
+ *
+ * The project ID is determined from, in order of preference:
+ *
+ *
+ * - DATASTORE_PROJECT_ID environment variable
+ *
- Compute Engine
+ *
+ *
+ * Credentials are taken from, in order of preference:
+ *
+ *
+ * - No credentials (if the DATASTORE_EMULATOR_HOST environment variable is set)
+ *
- Service Account specified by the DATASTORE_SERVICE_ACCOUNT and DATASTORE_PRIVATE_KEY_FILE
+ * environment variables
+ *
- Google Application Default as described here.
+ *
+ */
+ public static DatastoreOptions.Builder getOptionsFromEnv()
+ throws GeneralSecurityException, IOException {
+ DatastoreOptions.Builder options = new DatastoreOptions.Builder();
+ setProjectEndpointFromEnv(options);
+ options.credential(getCredentialFromEnv());
+ return options;
+ }
+
+ private static Credential getCredentialFromEnv() throws GeneralSecurityException, IOException {
+ if (System.getenv(LOCAL_HOST_ENV_VAR) != null) {
+ logger.log(
+ Level.INFO,
+ "{0} environment variable was set. Not using credentials.",
+ new Object[] {LOCAL_HOST_ENV_VAR});
+ return null;
+ }
+ String serviceAccount = System.getenv(SERVICE_ACCOUNT_ENV_VAR);
+ String privateKeyFile = System.getenv(PRIVATE_KEY_FILE_ENV_VAR);
+ if (serviceAccount != null && privateKeyFile != null) {
+ logger.log(
+ Level.INFO,
+ "{0} and {1} environment variables were set. " + "Using service account credential.",
+ new Object[] {SERVICE_ACCOUNT_ENV_VAR, PRIVATE_KEY_FILE_ENV_VAR});
+ return getServiceAccountCredential(serviceAccount, privateKeyFile);
+ }
+ return GoogleCredential.getApplicationDefault().createScoped(DatastoreOptions.SCOPES);
+ }
+
+ /**
+ * Determines the project id from the environment. Uses the following sources in order of
+ * preference:
+ *
+ *
+ * - Value of the DATASTORE_PROJECT_ID environment variable
+ *
- Compute Engine
+ *
+ *
+ * @throws IllegalStateException if the project ID cannot be determined
+ */
+ private static String getProjectIdFromEnv() {
+ if (System.getenv(PROJECT_ID_ENV_VAR) != null) {
+ return System.getenv(PROJECT_ID_ENV_VAR);
+ }
+ String projectIdFromComputeEngine = getProjectIdFromComputeEngine();
+ if (projectIdFromComputeEngine != null) {
+ return projectIdFromComputeEngine;
+ }
+ throw new IllegalStateException(
+ String.format(
+ "Could not determine project ID."
+ + " If you are not running on Compute Engine, set the"
+ + " %s environment variable.",
+ PROJECT_ID_ENV_VAR));
+ }
+
+ /**
+ * Gets the project ID from the Compute Engine metadata server. Returns {@code null} if the
+ * project ID cannot be determined (because, for instance, the code is not running on Compute
+ * Engine).
+ */
+ @Nullable
+ public static String getProjectIdFromComputeEngine() {
+ String cachedProjectId = projectIdFromComputeEngine.get();
+ return cachedProjectId != null ? cachedProjectId : queryProjectIdFromComputeEngine();
+ }
+
+ @Nullable
+ private static String queryProjectIdFromComputeEngine() {
+ HttpTransport transport;
+
+ try {
+ transport = newTransport();
+ } catch (GeneralSecurityException | IOException e) {
+ logger.log(Level.WARNING, "Failed to create HttpTransport.", e);
+ return null;
+ }
+
+ try {
+ GenericUrl projectIdUrl =
+ new GenericUrl("http://metadata/computeMetadata/v1/project/project-id");
+ HttpRequest request = transport.createRequestFactory().buildGetRequest(projectIdUrl);
+ request.getHeaders().set("Metadata-Flavor", "Google");
+ String result = request.execute().parseAsString();
+ projectIdFromComputeEngine.set(result);
+ return result;
+ } catch (IOException e) {
+ logger.log(Level.INFO, "Could not determine project ID from Compute Engine.", e);
+ return null;
+ }
+ }
+
+ private static void setProjectEndpointFromEnv(DatastoreOptions.Builder options) {
+ // DATASTORE_HOST is deprecated.
+ if (System.getenv("DATASTORE_HOST") != null) {
+ logger.warning(
+ String.format(
+ "Ignoring value of environment variable DATASTORE_HOST. "
+ + "To point datastore to a host running locally, use "
+ + "the environment variable %s.",
+ LOCAL_HOST_ENV_VAR));
+ }
+ String projectId = getProjectIdFromEnv();
+ if (System.getenv(URL_OVERRIDE_ENV_VAR) != null) {
+ options.projectEndpoint(
+ String.format("%s/projects/%s", System.getenv(URL_OVERRIDE_ENV_VAR), projectId));
+ return;
+ }
+ if (System.getenv(LOCAL_HOST_ENV_VAR) != null) {
+ options.projectId(projectId);
+ options.localHost(System.getenv(LOCAL_HOST_ENV_VAR));
+ return;
+ }
+ options.projectId(projectId);
+ return;
+ }
+
+ /**
+ * @see #getOptionsFromEnv()
+ */
+ public static Datastore getDatastoreFromEnv() throws GeneralSecurityException, IOException {
+ return DatastoreFactory.get().create(getOptionsFromEnv().build());
+ }
+
+ /**
+ * Gets a {@link QuerySplitter}.
+ *
+ * The returned {@link QuerySplitter#getSplits} cannot accept a query that contains inequality
+ * filters, a sort filter, or a missing kind.
+ */
+ public static QuerySplitter getQuerySplitter() {
+ return QuerySplitterImpl.INSTANCE;
+ }
+
+ public static Comparator getKeyComparator() {
+ return KeyComparator.INSTANCE;
+ }
+
+ /** Make a sort order for use in a query. */
+ public static PropertyOrder.Builder makeOrder(
+ String property, PropertyOrder.Direction direction) {
+ return PropertyOrder.newBuilder()
+ .setProperty(makePropertyReference(property))
+ .setDirection(direction);
+ }
+
+ /** Makes an ancestor filter. */
+ public static Filter.Builder makeAncestorFilter(Key ancestor) {
+ return makeFilter(
+ DatastoreHelper.KEY_PROPERTY_NAME,
+ PropertyFilter.Operator.HAS_ANCESTOR,
+ makeValue(ancestor));
+ }
+
+ /** Make a filter on a property for use in a query. */
+ public static Filter.Builder makeFilter(
+ String property, PropertyFilter.Operator operator, Value value) {
+ return Filter.newBuilder()
+ .setPropertyFilter(
+ PropertyFilter.newBuilder()
+ .setProperty(makePropertyReference(property))
+ .setOp(operator)
+ .setValue(value));
+ }
+
+ /** Make a filter on a property for use in a query. */
+ public static Filter.Builder makeFilter(
+ String property, PropertyFilter.Operator operator, Value.Builder value) {
+ return makeFilter(property, operator, value.build());
+ }
+
+ /** Make a composite filter from the given sub-filters using AND to combine filters. */
+ public static Filter.Builder makeAndFilter(Filter... subfilters) {
+ return makeAndFilter(Arrays.asList(subfilters));
+ }
+
+ /** Make a composite filter from the given sub-filters using AND to combine filters. */
+ public static Filter.Builder makeAndFilter(Iterable subfilters) {
+ return Filter.newBuilder()
+ .setCompositeFilter(
+ CompositeFilter.newBuilder()
+ .addAllFilters(subfilters)
+ .setOp(CompositeFilter.Operator.AND));
+ }
+
+ /** Make a property reference for use in a query. */
+ public static PropertyReference.Builder makePropertyReference(String propertyName) {
+ return PropertyReference.newBuilder().setName(propertyName);
+ }
+
+ /** Make an array value containing the specified values. */
+ public static Value.Builder makeValue(Iterable values) {
+ return Value.newBuilder().setArrayValue(ArrayValue.newBuilder().addAllValues(values));
+ }
+
+ /** Make a list value containing the specified values. */
+ public static Value.Builder makeValue(Value value1, Value value2, Value... rest) {
+ ArrayValue.Builder arrayValue = ArrayValue.newBuilder();
+ arrayValue.addValues(value1);
+ arrayValue.addValues(value2);
+ arrayValue.addAllValues(Arrays.asList(rest));
+ return Value.newBuilder().setArrayValue(arrayValue);
+ }
+
+ /** Make an array value containing the specified values. */
+ public static Value.Builder makeValue(
+ Value.Builder value1, Value.Builder value2, Value.Builder... rest) {
+ ArrayValue.Builder arrayValue = ArrayValue.newBuilder();
+ arrayValue.addValues(value1);
+ arrayValue.addValues(value2);
+ for (Value.Builder builder : rest) {
+ arrayValue.addValues(builder);
+ }
+ return Value.newBuilder().setArrayValue(arrayValue);
+ }
+
+ /** Make a key value. */
+ public static Value.Builder makeValue(Key key) {
+ return Value.newBuilder().setKeyValue(key);
+ }
+
+ /** Make a key value. */
+ public static Value.Builder makeValue(Key.Builder key) {
+ return makeValue(key.build());
+ }
+
+ /** Make an integer value. */
+ public static Value.Builder makeValue(long key) {
+ return Value.newBuilder().setIntegerValue(key);
+ }
+
+ /** Make a floating point value. */
+ public static Value.Builder makeValue(double value) {
+ return Value.newBuilder().setDoubleValue(value);
+ }
+
+ /** Make a boolean value. */
+ public static Value.Builder makeValue(boolean value) {
+ return Value.newBuilder().setBooleanValue(value);
+ }
+
+ /** Make a string value. */
+ public static Value.Builder makeValue(String value) {
+ return Value.newBuilder().setStringValue(value);
+ }
+
+ /** Make an entity value. */
+ public static Value.Builder makeValue(Entity entity) {
+ return Value.newBuilder().setEntityValue(entity);
+ }
+
+ /** Make a entity value. */
+ public static Value.Builder makeValue(Entity.Builder entity) {
+ return makeValue(entity.build());
+ }
+
+ /** Make a ByteString value. */
+ public static Value.Builder makeValue(ByteString blob) {
+ return Value.newBuilder().setBlobValue(blob);
+ }
+
+ /** Make a timestamp value given a date. */
+ public static Value.Builder makeValue(Date date) {
+ return Value.newBuilder().setTimestampValue(toTimestamp(date.getTime() * 1000L));
+ }
+
+ /** Makes a GeoPoint value. */
+ public static Value.Builder makeValue(LatLng value) {
+ return Value.newBuilder().setGeoPointValue(value);
+ }
+
+ /** Makes a GeoPoint value. */
+ public static Value.Builder makeValue(LatLng.Builder value) {
+ return makeValue(value.build());
+ }
+
+ private static Timestamp.Builder toTimestamp(long microseconds) {
+ long seconds = microseconds / MICROSECONDS_PER_SECOND;
+ long microsecondsRemainder = microseconds % MICROSECONDS_PER_SECOND;
+ if (microsecondsRemainder < 0) {
+ // Nanos must be positive even if microseconds is negative.
+ // Java modulus doesn't take care of this for us.
+ microsecondsRemainder += MICROSECONDS_PER_SECOND;
+ seconds -= 1;
+ }
+ return Timestamp.newBuilder()
+ .setSeconds(seconds)
+ .setNanos((int) microsecondsRemainder * NANOSECONDS_PER_MICROSECOND);
+ }
+
+ /**
+ * Make a key from the specified path of kind/id-or-name pairs and/or Keys.
+ *
+ * The id-or-name values must be either String, Long, Integer or Short.
+ *
+ *
The last id-or-name value may be omitted, in which case an entity without an id is created
+ * (for use with automatic id allocation).
+ *
+ *
The PartitionIds of all Keys in the path must be equal. The returned Key.Builder will use
+ * this PartitionId.
+ */
+ public static Key.Builder makeKey(Object... elements) {
+ Key.Builder key = Key.newBuilder();
+ PartitionId partitionId = null;
+ for (int pathIndex = 0; pathIndex < elements.length; pathIndex += 2) {
+ PathElement.Builder pathElement = PathElement.newBuilder();
+ Object element = elements[pathIndex];
+ if (element instanceof Key) {
+ Key subKey = (Key) element;
+ if (partitionId == null) {
+ partitionId = subKey.getPartitionId();
+ } else if (!partitionId.equals(subKey.getPartitionId())) {
+ throw new IllegalArgumentException(
+ "Partition IDs did not match, found: "
+ + partitionId
+ + " and "
+ + subKey.getPartitionId());
+ }
+ key.addAllPath(((Key) element).getPathList());
+ // We increment by 2, but since we got a Key argument we're only consuming 1 element in this
+ // iteration of the loop. Decrement the index so that when we jump by 2 we end up in the
+ // right spot.
+ pathIndex--;
+ } else {
+ String kind;
+ try {
+ kind = (String) element;
+ } catch (ClassCastException e) {
+ throw new IllegalArgumentException(
+ "Expected string or Key, got: " + element.getClass(), e);
+ }
+ pathElement.setKind(kind);
+ if (pathIndex + 1 < elements.length) {
+ Object value = elements[pathIndex + 1];
+ if (value instanceof String) {
+ pathElement.setName((String) value);
+ } else if (value instanceof Long) {
+ pathElement.setId((Long) value);
+ } else if (value instanceof Integer) {
+ pathElement.setId((Integer) value);
+ } else if (value instanceof Short) {
+ pathElement.setId((Short) value);
+ } else {
+ throw new IllegalArgumentException(
+ "Expected string or integer, got: " + value.getClass());
+ }
+ }
+ key.addPath(pathElement);
+ }
+ }
+ if (partitionId != null && !partitionId.equals(PartitionId.getDefaultInstance())) {
+ key.setPartitionId(partitionId);
+ }
+ return key;
+ }
+
+ /**
+ * @return the double contained in value
+ * @throws IllegalArgumentException if the value does not contain a double.
+ */
+ public static double getDouble(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.DOUBLE_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a double.");
+ }
+ return value.getDoubleValue();
+ }
+
+ /**
+ * @return the key contained in value
+ * @throws IllegalArgumentException if the value does not contain a key.
+ */
+ public static Key getKey(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.KEY_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a key.");
+ }
+ return value.getKeyValue();
+ }
+
+ /**
+ * @return the blob contained in value
+ * @throws IllegalArgumentException if the value does not contain a blob.
+ */
+ public static ByteString getByteString(Value value) {
+ if (value.getMeaning() == 18 && value.getValueTypeCase() == ValueTypeCase.STRING_VALUE) {
+ return value.getStringValueBytes();
+ } else if (value.getValueTypeCase() == ValueTypeCase.BLOB_VALUE) {
+ return value.getBlobValue();
+ }
+ throw new IllegalArgumentException("Value does not contain a blob.");
+ }
+
+ /**
+ * @return the entity contained in value
+ * @throws IllegalArgumentException if the value does not contain an entity.
+ */
+ public static Entity getEntity(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.ENTITY_VALUE) {
+ throw new IllegalArgumentException("Value does not contain an Entity.");
+ }
+ return value.getEntityValue();
+ }
+
+ /**
+ * @return the string contained in value
+ * @throws IllegalArgumentException if the value does not contain a string.
+ */
+ public static String getString(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.STRING_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a string.");
+ }
+ return value.getStringValue();
+ }
+
+ /**
+ * @return the boolean contained in value
+ * @throws IllegalArgumentException if the value does not contain a boolean.
+ */
+ public static boolean getBoolean(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.BOOLEAN_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a boolean.");
+ }
+ return value.getBooleanValue();
+ }
+
+ /**
+ * @return the long contained in value
+ * @throws IllegalArgumentException if the value does not contain a long.
+ */
+ public static long getLong(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.INTEGER_VALUE) {
+ throw new IllegalArgumentException("Value does not contain an integer.");
+ }
+ return value.getIntegerValue();
+ }
+
+ /**
+ * @return the timestamp in microseconds contained in value
+ * @throws IllegalArgumentException if the value does not contain a timestamp.
+ */
+ public static long getTimestamp(Value value) {
+ if (value.getMeaning() == 18 && value.getValueTypeCase() == ValueTypeCase.INTEGER_VALUE) {
+ return value.getIntegerValue();
+ } else if (value.getValueTypeCase() == ValueTypeCase.TIMESTAMP_VALUE) {
+ return toMicroseconds(value.getTimestampValue());
+ }
+ throw new IllegalArgumentException("Value does not contain a timestamp.");
+ }
+
+ private static long toMicroseconds(TimestampOrBuilder timestamp) {
+ // Nanosecond precision is lost.
+ return timestamp.getSeconds() * MICROSECONDS_PER_SECOND
+ + timestamp.getNanos() / NANOSECONDS_PER_MICROSECOND;
+ }
+
+ /**
+ * @return the array contained in value as a list.
+ * @throws IllegalArgumentException if the value does not contain an array.
+ */
+ public static List getList(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.ARRAY_VALUE) {
+ throw new IllegalArgumentException("Value does not contain an array.");
+ }
+ return value.getArrayValue().getValuesList();
+ }
+
+ /**
+ * Convert a timestamp value into a {@link Date} clipping off the microseconds.
+ *
+ * @param value a timestamp value to convert
+ * @return the resulting {@link Date}
+ * @throws IllegalArgumentException if the value does not contain a timestamp.
+ */
+ public static Date toDate(Value value) {
+ return new Date(getTimestamp(value) / 1000);
+ }
+
+ /**
+ * @param entity the entity to insert
+ * @return a mutation that will insert an entity
+ */
+ public static Mutation.Builder makeInsert(Entity entity) {
+ return Mutation.newBuilder().setInsert(entity);
+ }
+
+ /**
+ * @param entity the entity to update
+ * @return a mutation that will update an entity
+ */
+ public static Mutation.Builder makeUpdate(Entity entity) {
+ return Mutation.newBuilder().setUpdate(entity);
+ }
+
+ /**
+ * @param entity the entity to upsert
+ * @return a mutation that will upsert an entity
+ */
+ public static Mutation.Builder makeUpsert(Entity entity) {
+ return Mutation.newBuilder().setUpsert(entity);
+ }
+
+ /**
+ * @param key the key of the entity to delete
+ * @return a mutation that will delete an entity
+ */
+ public static Mutation.Builder makeDelete(Key key) {
+ return Mutation.newBuilder().setDelete(key);
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/DatastoreOptions.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/DatastoreOptions.java
new file mode 100644
index 000000000000..780a3c940184
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/DatastoreOptions.java
@@ -0,0 +1,204 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.HttpRequestInitializer;
+import com.google.api.client.http.HttpTransport;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * An immutable object containing settings for the datastore.
+ *
+ * Example for connecting to a datastore:
+ *
+ *
+ * DatastoreOptions options = new DatastoreOptions.Builder()
+ * .projectId("my-project-id")
+ * .credential(DatastoreHelper.getComputeEngineCredential())
+ * .build();
+ * DatastoreFactory.get().create(options);
+ *
+ *
+ * The options should be passed to {@link DatastoreFactory#create}.
+ */
+public class DatastoreOptions {
+ private final String projectId;
+
+ private final String projectEndpoint;
+ private final String host;
+ private final String localHost;
+
+ private final HttpRequestInitializer initializer;
+
+ private final Credential credential;
+ private final HttpTransport transport;
+ public static final List SCOPES =
+ Arrays.asList("https://www.googleapis.com/auth/datastore");
+
+ DatastoreOptions(Builder b) {
+ checkArgument(
+ b.projectId != null || b.projectEndpoint != null,
+ "Either project ID or project endpoint must be provided.");
+ this.projectId = b.projectId;
+ this.projectEndpoint = b.projectEndpoint;
+ this.host = b.host;
+ this.localHost = b.localHost;
+ this.initializer = b.initializer;
+ this.credential = b.credential;
+ this.transport = b.transport;
+ }
+
+ /** Builder for {@link DatastoreOptions}. */
+ public static class Builder {
+ private static final String PROJECT_ENDPOINT_AND_PROJECT_ID_ERROR =
+ "Cannot set both project endpoint and project ID.";
+ private static final String PROJECT_ENDPOINT_AND_HOST_ERROR =
+ "Can set at most one of project endpoint, host, and local host.";
+
+ private String projectId;
+
+ private String projectEndpoint;
+ private String host;
+ private String localHost;
+ private HttpRequestInitializer initializer;
+ private Credential credential;
+ private HttpTransport transport;
+
+ public Builder() {}
+
+ public Builder(DatastoreOptions options) {
+ this.projectId = options.projectId;
+ this.projectEndpoint = options.projectEndpoint;
+ this.host = options.host;
+ this.localHost = options.localHost;
+ this.initializer = options.initializer;
+ this.credential = options.credential;
+ this.transport = options.transport;
+ }
+
+ public DatastoreOptions build() {
+ return new DatastoreOptions(this);
+ }
+
+ /** Sets the project ID used to access Cloud Datastore. */
+ public Builder projectId(String projectId) {
+ checkArgument(projectEndpoint == null, PROJECT_ENDPOINT_AND_PROJECT_ID_ERROR);
+ this.projectId = projectId;
+ return this;
+ }
+
+ /**
+ * Sets the host used to access Cloud Datastore. To connect to the Cloud Datastore Emulator, use
+ * {@link #localHost} instead.
+ */
+ public Builder host(String host) {
+ checkArgument(projectEndpoint == null && localHost == null, PROJECT_ENDPOINT_AND_HOST_ERROR);
+ if (includesScheme(host)) {
+ throw new IllegalArgumentException(
+ String.format("Host \"%s\" must not include scheme.", host));
+ }
+ this.host = host;
+ return this;
+ }
+
+ /**
+ * Configures the client to access Cloud Datastore on a local host (typically a Cloud Datastore
+ * Emulator instance). Call this method also configures the client not to attach credentials to
+ * requests.
+ */
+ public Builder localHost(String localHost) {
+ checkArgument(projectEndpoint == null && host == null, PROJECT_ENDPOINT_AND_HOST_ERROR);
+ if (includesScheme(localHost)) {
+ throw new IllegalArgumentException(
+ String.format("Local host \"%s\" must not include scheme.", localHost));
+ }
+ this.localHost = localHost;
+ return this;
+ }
+
+ /**
+ * Sets the project endpoint used to access Cloud Datastore. Prefer using {@link #projectId}
+ * and/or {@link #host}/{@link #localHost} when possible.
+ *
+ * @deprecated Use {@link #projectId} and/or {@link #host}/{@link #localHost} instead.
+ */
+ @Deprecated
+ public Builder projectEndpoint(String projectEndpoint) {
+ checkArgument(projectId == null, PROJECT_ENDPOINT_AND_PROJECT_ID_ERROR);
+ checkArgument(localHost == null && host == null, PROJECT_ENDPOINT_AND_HOST_ERROR);
+ if (!includesScheme(projectEndpoint)) {
+ throw new IllegalArgumentException(
+ String.format("Project endpoint \"%s\" must include scheme.", projectEndpoint));
+ }
+ this.projectEndpoint = projectEndpoint;
+ return this;
+ }
+
+ /** Sets the (optional) initializer to run on HTTP requests to Cloud Datastore. */
+ public Builder initializer(HttpRequestInitializer initializer) {
+ this.initializer = initializer;
+ return this;
+ }
+
+ /** Sets the Google APIs {@link Credential} used to access Cloud Datastore. */
+ public Builder credential(Credential credential) {
+ this.credential = credential;
+ return this;
+ }
+
+ /** Sets the transport used to access Cloud Datastore. */
+ public Builder transport(HttpTransport transport) {
+ this.transport = transport;
+ return this;
+ }
+
+ private static boolean includesScheme(String url) {
+ return url.startsWith("http://") || url.startsWith("https://");
+ }
+ }
+
+ public String getProjectId() {
+ return projectId;
+ }
+
+ public String getProjectEndpoint() {
+ return projectEndpoint;
+ }
+
+ public String getHost() {
+ return host;
+ }
+
+ public String getLocalHost() {
+ return localHost;
+ }
+
+ public HttpRequestInitializer getInitializer() {
+ return initializer;
+ }
+
+ public Credential getCredential() {
+ return credential;
+ }
+
+ public HttpTransport getTransport() {
+ return transport;
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/EndToEndChecksumHandler.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/EndToEndChecksumHandler.java
new file mode 100644
index 000000000000..507625a47cc7
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/EndToEndChecksumHandler.java
@@ -0,0 +1,86 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import com.google.api.client.http.HttpResponse;
+import com.google.common.hash.HashCode;
+import com.google.common.hash.Hasher;
+import com.google.common.hash.Hashing;
+
+/** This class provides End-to-End Checksum API for http protocol. */
+class EndToEndChecksumHandler {
+ /** The checksum http header on http requests */
+ static final String HTTP_REQUEST_CHECKSUM_HEADER = "x-request-checksum-348659783";
+
+ /** The checksum http header on http responses */
+ static final String HTTP_RESPONSE_CHECKSUM_HEADER = "x-response-checksum-348659783";
+
+ final Hasher hasher = EndToEndChecksumHandler.getNewCrc32cHasher();
+
+ /**
+ * Create and return checksum as a string value for the input 'bytes'.
+ *
+ * @param bytes raw message for which the checksum is being computed
+ * @return computed checksum as a hex string
+ */
+ static String computeChecksum(byte[] bytes) {
+ if (bytes == null || (bytes.length == 0)) {
+ return null;
+ }
+ HashCode hc = getNewCrc32cHasher().putBytes(bytes).hash();
+ return hashToString(hc);
+ }
+
+ private static String hashToString(HashCode hc) {
+ return String.valueOf(Integer.toUnsignedLong(hc.asInt()));
+ }
+
+ private static Hasher getNewCrc32cHasher() {
+ return Hashing.crc32c().newHasher();
+ }
+
+ /**
+ * Validates the checksum for the given input 'bytes' and returns true if valid, false otherwise.
+ *
+ * @param checksum the checksum as a hex string
+ * @param bytes the raw message for which the checksum was sent
+ * @return {@code true} if input checksum is valid for the input bytes; {@code false} otherwise
+ */
+ static boolean validateChecksum(String checksum, byte[] bytes) {
+ return checksum != null
+ && !checksum.isEmpty()
+ && bytes != null
+ && bytes.length > 0
+ && checksum.equals(computeChecksum(bytes));
+ }
+
+ static boolean hasChecksumHeader(HttpResponse response) {
+ String checksum = getChecksumHeader(response);
+ return checksum != null && !checksum.isEmpty();
+ }
+
+ static String getChecksumHeader(HttpResponse response) {
+ return response.getHeaders().getFirstHeaderStringValue(HTTP_RESPONSE_CHECKSUM_HEADER);
+ }
+
+ void update(byte[] bytes, int off, int len) {
+ hasher.putBytes(bytes, off, len);
+ }
+
+ String hash() {
+ return hashToString(hasher.hash());
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/QuerySplitter.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/QuerySplitter.java
new file mode 100644
index 000000000000..e704f4c932ad
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/QuerySplitter.java
@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import com.google.api.core.BetaApi;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Query;
+import com.google.protobuf.Timestamp;
+import java.util.List;
+
+/** Provides the ability to split a query into multiple shards. */
+public interface QuerySplitter {
+
+ /**
+ * Returns a list of sharded {@link Query}s for the given query.
+ *
+ * This will create up to the desired number of splits, however it may return less splits if
+ * the desired number of splits is unavailable. This will happen if the number of split points
+ * provided by the underlying Datastore is less than the desired number, which will occur if the
+ * number of results for the query is too small.
+ *
+ * @param query the query to split.
+ * @param partition the partition the query is running in.
+ * @param numSplits the desired number of splits.
+ * @param datastore the datastore to run on.
+ * @throws DatastoreException if there was a datastore error while generating query splits.
+ * @throws IllegalArgumentException if the given query or numSplits was invalid.
+ */
+ List getSplits(Query query, PartitionId partition, int numSplits, Datastore datastore)
+ throws DatastoreException;
+
+ /**
+ * Same as {@link #getSplits(Query, PartitionId, int, Datastore)} but the splits are based on
+ * {@code readTime}, and the returned sharded {@link Query}s should also be executed with {@code
+ * readTime}. Reading from a timestamp is currently a private preview feature in Datastore.
+ */
+ @BetaApi
+ default List getSplits(
+ Query query, PartitionId partition, int numSplits, Datastore datastore, Timestamp readTime)
+ throws DatastoreException {
+ throw new UnsupportedOperationException("Not implemented.");
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/QuerySplitterImpl.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/QuerySplitterImpl.java
new file mode 100644
index 000000000000..3eac40fa111c
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/QuerySplitterImpl.java
@@ -0,0 +1,308 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static com.google.datastore.v1.client.DatastoreHelper.makeAndFilter;
+
+import com.google.api.core.BetaApi;
+import com.google.datastore.v1.EntityResult;
+import com.google.datastore.v1.Filter;
+import com.google.datastore.v1.Key;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Projection;
+import com.google.datastore.v1.PropertyFilter;
+import com.google.datastore.v1.PropertyFilter.Operator;
+import com.google.datastore.v1.PropertyOrder.Direction;
+import com.google.datastore.v1.PropertyReference;
+import com.google.datastore.v1.Query;
+import com.google.datastore.v1.QueryResultBatch;
+import com.google.datastore.v1.QueryResultBatch.MoreResultsType;
+import com.google.datastore.v1.ReadOptions;
+import com.google.datastore.v1.RunQueryRequest;
+import com.google.protobuf.Timestamp;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.List;
+import javax.annotation.Nullable;
+
+/**
+ * Provides the ability to split a query into multiple shards using Cloud Datastore.
+ *
+ * This implementation of the QuerySplitter uses the __scatter__ property to gather random split
+ * points for a query.
+ */
+final class QuerySplitterImpl implements QuerySplitter {
+
+ /** The number of keys to sample for each split. * */
+ private static final int KEYS_PER_SPLIT = 32;
+
+ private static final EnumSet UNSUPPORTED_OPERATORS =
+ EnumSet.of(
+ Operator.LESS_THAN,
+ Operator.LESS_THAN_OR_EQUAL,
+ Operator.GREATER_THAN,
+ Operator.GREATER_THAN_OR_EQUAL);
+
+ static final QuerySplitter INSTANCE = new QuerySplitterImpl();
+
+ private QuerySplitterImpl() {
+ // No initialization required.
+ }
+
+ @Override
+ public List getSplits(
+ Query query, PartitionId partition, int numSplits, Datastore datastore)
+ throws DatastoreException, IllegalArgumentException {
+ return getSplitsInternal(query, partition, numSplits, datastore, null);
+ }
+
+ @BetaApi
+ @Override
+ public List getSplits(
+ Query query, PartitionId partition, int numSplits, Datastore datastore, Timestamp readTime)
+ throws DatastoreException, IllegalArgumentException {
+ return getSplitsInternal(query, partition, numSplits, datastore, readTime);
+ }
+
+ private List getSplitsInternal(
+ Query query,
+ PartitionId partition,
+ int numSplits,
+ Datastore datastore,
+ @Nullable Timestamp readTime)
+ throws DatastoreException, IllegalArgumentException {
+ List splits = new ArrayList(numSplits);
+ if (numSplits == 1) {
+ splits.add(query);
+ return splits;
+ }
+ validateQuery(query);
+ validateSplitSize(numSplits);
+
+ List scatterKeys = getScatterKeys(numSplits, query, partition, datastore, readTime);
+ Key lastKey = null;
+ for (Key nextKey : getSplitKey(scatterKeys, numSplits)) {
+ splits.add(createSplit(lastKey, nextKey, query));
+ lastKey = nextKey;
+ }
+ splits.add(createSplit(lastKey, null, query));
+ return splits;
+ }
+
+ /**
+ * Verify that the given number of splits is not out of bounds.
+ *
+ * @param numSplits the number of splits.
+ * @throws IllegalArgumentException if the split size is invalid.
+ */
+ private void validateSplitSize(int numSplits) throws IllegalArgumentException {
+ if (numSplits < 1) {
+ throw new IllegalArgumentException("The number of splits must be greater than 0.");
+ }
+ }
+
+ /**
+ * Validates that we only have allowable filters.
+ *
+ * Note that equality and ancestor filters are allowed, however they may result in inefficient
+ * sharding.
+ */
+ private void validateFilter(Filter filter) throws IllegalArgumentException {
+ switch (filter.getFilterTypeCase()) {
+ case COMPOSITE_FILTER:
+ for (Filter subFilter : filter.getCompositeFilter().getFiltersList()) {
+ validateFilter(subFilter);
+ }
+ break;
+ case PROPERTY_FILTER:
+ if (UNSUPPORTED_OPERATORS.contains(filter.getPropertyFilter().getOp())) {
+ throw new IllegalArgumentException("Query cannot have any inequality filters.");
+ }
+ break;
+ default:
+ throw new IllegalArgumentException(
+ "Unsupported filter type: " + filter.getFilterTypeCase());
+ }
+ }
+
+ /**
+ * Verifies that the given query can be properly scattered.
+ *
+ * @param query the query to verify
+ * @throws IllegalArgumentException if the query is invalid.
+ */
+ private void validateQuery(Query query) throws IllegalArgumentException {
+ if (query.getKindCount() != 1) {
+ throw new IllegalArgumentException("Query must have exactly one kind.");
+ }
+ if (query.getOrderCount() != 0) {
+ throw new IllegalArgumentException("Query cannot have any sort orders.");
+ }
+ if (query.hasFilter()) {
+ validateFilter(query.getFilter());
+ }
+ }
+
+ /**
+ * Create a new {@link Query} given the query and range.
+ *
+ * @param lastKey the previous key. If null then assumed to be the beginning.
+ * @param nextKey the next key. If null then assumed to be the end.
+ * @param query the desired query.
+ */
+ private Query createSplit(Key lastKey, Key nextKey, Query query) {
+ if (lastKey == null && nextKey == null) {
+ return query;
+ }
+ List keyFilters = new ArrayList();
+ if (query.hasFilter()) {
+ keyFilters.add(query.getFilter());
+ }
+ if (lastKey != null) {
+ Filter lowerBound =
+ DatastoreHelper.makeFilter(
+ DatastoreHelper.KEY_PROPERTY_NAME,
+ PropertyFilter.Operator.GREATER_THAN_OR_EQUAL,
+ DatastoreHelper.makeValue(lastKey))
+ .build();
+ keyFilters.add(lowerBound);
+ }
+ if (nextKey != null) {
+ Filter upperBound =
+ DatastoreHelper.makeFilter(
+ DatastoreHelper.KEY_PROPERTY_NAME,
+ PropertyFilter.Operator.LESS_THAN,
+ DatastoreHelper.makeValue(nextKey))
+ .build();
+ keyFilters.add(upperBound);
+ }
+ return Query.newBuilder(query).setFilter(makeAndFilter(keyFilters)).build();
+ }
+
+ /**
+ * Gets a list of split keys given a desired number of splits.
+ *
+ * This list will contain multiple split keys for each split. Only a single split key will be
+ * chosen as the split point, however providing multiple keys allows for more uniform sharding.
+ *
+ * @param numSplits the number of desired splits.
+ * @param query the user query.
+ * @param partition the partition to run the query in.
+ * @param datastore the datastore containing the data.
+ * @param readTime read time at which to get the split keys from the datastore.
+ * @throws DatastoreException if there was an error when executing the datastore query.
+ */
+ private List getScatterKeys(
+ int numSplits,
+ Query query,
+ PartitionId partition,
+ Datastore datastore,
+ @Nullable Timestamp readTime)
+ throws DatastoreException {
+ Query.Builder scatterPointQuery = createScatterQuery(query, numSplits);
+
+ List keySplits = new ArrayList();
+
+ QueryResultBatch batch;
+ do {
+ RunQueryRequest.Builder scatterRequest =
+ RunQueryRequest.newBuilder().setPartitionId(partition).setQuery(scatterPointQuery);
+ scatterRequest.setProjectId(partition.getProjectId());
+ scatterRequest.setDatabaseId(partition.getDatabaseId());
+ if (readTime != null) {
+ scatterRequest.setReadOptions(ReadOptions.newBuilder().setReadTime(readTime).build());
+ }
+ batch = datastore.runQuery(scatterRequest.build()).getBatch();
+ for (EntityResult result : batch.getEntityResultsList()) {
+ keySplits.add(result.getEntity().getKey());
+ }
+ scatterPointQuery.setStartCursor(batch.getEndCursor());
+ scatterPointQuery
+ .getLimitBuilder()
+ .setValue(scatterPointQuery.getLimit().getValue() - batch.getEntityResultsCount());
+ } while (batch.getMoreResults() == MoreResultsType.NOT_FINISHED);
+ Collections.sort(keySplits, DatastoreHelper.getKeyComparator());
+ return keySplits;
+ }
+
+ /**
+ * Creates a scatter query from the given user query
+ *
+ * @param query the user's query.
+ * @param numSplits the number of splits to create.
+ */
+ private Query.Builder createScatterQuery(Query query, int numSplits) {
+ // TODO(pcostello): We can potentially support better splits with equality filters in our query
+ // if there exists a composite index on property, __scatter__, __key__. Until an API for
+ // metadata exists, this isn't possible. Note that ancestor and inequality queries fall into
+ // the same category.
+ Query.Builder scatterPointQuery = Query.newBuilder();
+ scatterPointQuery.addAllKind(query.getKindList());
+ scatterPointQuery.addOrder(
+ DatastoreHelper.makeOrder(DatastoreHelper.SCATTER_PROPERTY_NAME, Direction.ASCENDING));
+ // There is a split containing entities before and after each scatter entity:
+ // ||---*------*------*------*------*------*------*---|| = scatter entity
+ // If we represent each split as a region before a scatter entity, there is an extra region
+ // following the last scatter point. Thus, we do not need the scatter entities for the last
+ // region.
+ scatterPointQuery.getLimitBuilder().setValue((numSplits - 1) * KEYS_PER_SPLIT);
+ scatterPointQuery.addProjection(
+ Projection.newBuilder().setProperty(PropertyReference.newBuilder().setName("__key__")));
+ return scatterPointQuery;
+ }
+
+ /**
+ * Given a list of keys and a number of splits find the keys to split on.
+ *
+ * @param keys the list of keys.
+ * @param numSplits the number of splits.
+ */
+ private Iterable getSplitKey(List keys, int numSplits) {
+ // If the number of keys is less than the number of splits, we are limited in the number of
+ // splits we can make.
+ if (keys.size() < numSplits - 1) {
+ return keys;
+ }
+
+ // Calculate the number of keys per split. This should be KEYS_PER_SPLIT, but may
+ // be less if there are not KEYS_PER_SPLIT * (numSplits - 1) scatter entities.
+ //
+ // Consider the following dataset, where - represents an entity and * represents an entity
+ // that is returned as a scatter entity:
+ // ||---*-----*----*-----*-----*------*----*----||
+ // If we want 4 splits in this data, the optimal split would look like:
+ // ||---*-----*----*-----*-----*------*----*----||
+ // | | |
+ // The scatter keys in the last region are not useful to us, so we never request them:
+ // ||---*-----*----*-----*-----*------*---------||
+ // | | |
+ // With 6 scatter keys we want to set scatter points at indexes: 1, 3, 5.
+ //
+ // We keep this as a double so that any "fractional" keys per split get distributed throughout
+ // the splits and don't make the last split significantly larger than the rest.
+ double numKeysPerSplit = Math.max(1.0, ((double) keys.size()) / (numSplits - 1));
+
+ List keysList = new ArrayList(numSplits - 1);
+ // Grab the last sample for each split, otherwise the first split will be too small.
+ for (int i = 1; i < numSplits; i++) {
+ int splitIndex = (int) Math.round(i * numKeysPerSplit) - 1;
+ keysList.add(keys.get(splitIndex));
+ }
+
+ return keysList;
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/RemoteRpc.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/RemoteRpc.java
new file mode 100644
index 000000000000..75fc84d62e28
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/RemoteRpc.java
@@ -0,0 +1,254 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import com.google.api.client.http.GenericUrl;
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpRequestFactory;
+import com.google.api.client.http.HttpRequestInitializer;
+import com.google.api.client.http.HttpResponse;
+import com.google.api.client.http.HttpStatusCodes;
+import com.google.api.client.http.protobuf.ProtoHttpContent;
+import com.google.api.client.util.IOUtils;
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.Strings;
+import com.google.protobuf.MessageLite;
+import com.google.rpc.Code;
+import com.google.rpc.Status;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.SocketTimeoutException;
+import java.nio.charset.Charset;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.logging.Logger;
+
+/**
+ * An RPC transport that sends protocol buffers over HTTP.
+ *
+ * This class is thread-safe.
+ */
+class RemoteRpc {
+ private static final Logger logger = Logger.getLogger(RemoteRpc.class.getName());
+
+ @VisibleForTesting static final String API_FORMAT_VERSION_HEADER = "X-Goog-Api-Format-Version";
+ private static final String API_FORMAT_VERSION = "2";
+
+ @VisibleForTesting static final String X_GOOG_REQUEST_PARAMS_HEADER = "x-goog-request-params";
+
+ private final HttpRequestFactory client;
+ private final HttpRequestInitializer initializer;
+ private final String url;
+ private final AtomicInteger rpcCount = new AtomicInteger(0);
+ // Not final - so it can be set/reset in Unittests
+ private static boolean enableE2EChecksum =
+ Boolean.parseBoolean(System.getenv("GOOGLE_CLOUD_DATASTORE_HTTP_ENABLE_E2E_CHECKSUM"));
+
+ RemoteRpc(HttpRequestFactory client, HttpRequestInitializer initializer, String url) {
+ this.client = client;
+ this.initializer = initializer;
+ this.url = url;
+ try {
+ resolveURL("dummyRpc");
+ } catch (Exception e) {
+ throw new IllegalArgumentException(
+ "Unable to construct RemoteRpc due to unsupported url: <" + url + ">", e);
+ }
+ }
+
+ /**
+ * Makes an RPC call using the client. Logs how long it took and any exceptions.
+ *
+ *
NOTE: The request could be an InputStream too, but the http client will need to find its
+ * length, which will require buffering it anyways.
+ *
+ * @throws DatastoreException if the RPC fails.
+ */
+ public InputStream call(
+ String methodName, MessageLite request, String projectId, String databaseId)
+ throws DatastoreException {
+ logger.fine("remote datastore call " + methodName);
+
+ long startTime = System.currentTimeMillis();
+ try {
+ HttpResponse httpResponse;
+ try {
+ rpcCount.incrementAndGet();
+ ProtoHttpContent payload = new ProtoHttpContent(request);
+ HttpRequest httpRequest = client.buildPostRequest(resolveURL(methodName), payload);
+ setHeaders(request, httpRequest, projectId, databaseId);
+ // Don't throw an HTTPResponseException on error. It converts the response to a String and
+ // throws away the original, whereas we need the raw bytes to parse it as a proto.
+ httpRequest.setThrowExceptionOnExecuteError(false);
+ // Datastore requests typically time out after 60s; set the read timeout to slightly longer
+ // than that by default (can be overridden via the HttpRequestInitializer).
+ httpRequest.setReadTimeout(65 * 1000);
+ if (initializer != null) {
+ initializer.initialize(httpRequest);
+ }
+ httpResponse = httpRequest.execute();
+ if (!httpResponse.isSuccessStatusCode()) {
+ try (InputStream content = httpResponse.getContent()) {
+ throw makeException(
+ url,
+ methodName,
+ content,
+ httpResponse.getContentType(),
+ httpResponse.getContentCharset(),
+ null,
+ httpResponse.getStatusCode());
+ }
+ }
+ InputStream inputStream = httpResponse.getContent();
+ return enableE2EChecksum && EndToEndChecksumHandler.hasChecksumHeader(httpResponse)
+ ? new ChecksumEnforcingInputStream(inputStream, httpResponse)
+ : inputStream;
+ } catch (SocketTimeoutException e) {
+ throw makeException(url, methodName, Code.DEADLINE_EXCEEDED, "Deadline exceeded", e);
+ } catch (IOException e) {
+ throw makeException(url, methodName, Code.UNAVAILABLE, "I/O error", e);
+ }
+ } finally {
+ long elapsedTime = System.currentTimeMillis() - startTime;
+ logger.fine("remote datastore call " + methodName + " took " + elapsedTime + " ms");
+ }
+ }
+
+ @VisibleForTesting
+ void setHeaders(
+ MessageLite request, HttpRequest httpRequest, String projectId, String databaseId) {
+ httpRequest.getHeaders().put(API_FORMAT_VERSION_HEADER, API_FORMAT_VERSION);
+ StringBuilder builder = new StringBuilder("project_id=");
+ builder.append(projectId);
+ if (!Strings.isNullOrEmpty(databaseId)) {
+ builder.append("&database_id=");
+ builder.append(databaseId);
+ }
+ httpRequest.getHeaders().put(X_GOOG_REQUEST_PARAMS_HEADER, builder.toString());
+ if (enableE2EChecksum && request != null) {
+ String checksum = EndToEndChecksumHandler.computeChecksum(request.toByteArray());
+ if (checksum != null) {
+ httpRequest
+ .getHeaders()
+ .put(EndToEndChecksumHandler.HTTP_REQUEST_CHECKSUM_HEADER, checksum);
+ }
+ }
+ }
+
+ @VisibleForTesting
+ HttpRequestFactory getClient() {
+ return client;
+ }
+
+ @VisibleForTesting
+ static void setSystemEnvE2EChecksum(boolean enableE2EChecksum) {
+ RemoteRpc.enableE2EChecksum = enableE2EChecksum;
+ }
+
+ void resetRpcCount() {
+ rpcCount.set(0);
+ }
+
+ int getRpcCount() {
+ return rpcCount.get();
+ }
+
+ public String getUrl() {
+ return url;
+ }
+
+ GenericUrl resolveURL(String path) {
+ return new GenericUrl(url + ":" + path);
+ }
+
+ HttpRequestFactory getHttpRequestFactory() {
+ return client;
+ }
+
+ public static DatastoreException makeException(
+ String url, String methodName, Code code, String message, Throwable cause) {
+ logger.fine("remote datastore call " + methodName + " against " + url + " failed: " + message);
+ return new DatastoreException(methodName, code, message, cause);
+ }
+
+ static DatastoreException makeException(
+ String url,
+ String methodName,
+ InputStream content,
+ String contentType,
+ Charset contentCharset,
+ Throwable cause,
+ int httpStatusCode) {
+ if (!contentType.equals("application/x-protobuf")) {
+ String responseContent;
+ try {
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ IOUtils.copy(content, out, false);
+ responseContent = out.toString(contentCharset.name());
+ } catch (IOException e) {
+ responseContent = "";
+ }
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Non-protobuf error: %s. HTTP status code was %d.", responseContent, httpStatusCode),
+ cause);
+ }
+
+ Status rpcStatus;
+ try {
+ rpcStatus = Status.parseFrom(content);
+ } catch (IOException e) {
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Unable to parse Status protocol buffer: HTTP status code was %s.", httpStatusCode),
+ e);
+ }
+
+ Code code = Code.forNumber(rpcStatus.getCode());
+ if (code == null) {
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Invalid error code: %d. Message: %s.", rpcStatus.getCode(), rpcStatus.getMessage()),
+ cause);
+ } else if (code == Code.OK) {
+ // We can end up here because there was no response body (and we successfully parsed an
+ // empty Status message). This may happen for 401s in particular due to special handling
+ // in low-level HTTP libraries.
+ if (httpStatusCode == HttpStatusCodes.STATUS_CODE_UNAUTHORIZED) {
+ return makeException(url, methodName, Code.UNAUTHENTICATED, "Unauthenticated.", cause);
+ }
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Unexpected OK error code with HTTP status code of %d. Message: %s.",
+ httpStatusCode, rpcStatus.getMessage()),
+ cause);
+ }
+
+ return makeException(url, methodName, code, rpcStatus.getMessage(), cause);
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/testing/MockCredential.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/testing/MockCredential.java
new file mode 100644
index 000000000000..7831d2a03f6d
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/testing/MockCredential.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2026 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.datastore.v1.client.testing;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.HttpRequest;
+import java.io.IOException;
+
+/** Fake credential used for testing purpose. */
+public class MockCredential extends Credential {
+ public MockCredential() {
+ super(
+ new AccessMethod() {
+ @Override
+ public void intercept(HttpRequest request, String accessToken) throws IOException {}
+
+ @Override
+ public String getAccessTokenFromRequest(HttpRequest request) {
+ return "MockAccessToken";
+ }
+ });
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/testing/MockDatastoreFactory.java b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/testing/MockDatastoreFactory.java
new file mode 100644
index 000000000000..bbe8468258a9
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/java/com/google/datastore/v1/client/testing/MockDatastoreFactory.java
@@ -0,0 +1,137 @@
+/*
+ * Copyright 2026 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.datastore.v1.client.testing;
+
+import static com.google.common.base.Preconditions.checkState;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.GenericUrl;
+import com.google.api.client.http.HttpRequestFactory;
+import com.google.api.client.http.HttpStatusCodes;
+import com.google.api.client.http.HttpTransport;
+import com.google.api.client.http.LowLevelHttpRequest;
+import com.google.api.client.http.LowLevelHttpResponse;
+import com.google.api.client.testing.http.MockHttpTransport;
+import com.google.api.client.testing.http.MockLowLevelHttpRequest;
+import com.google.api.client.testing.http.MockLowLevelHttpResponse;
+import com.google.api.client.testing.util.TestableByteArrayInputStream;
+import com.google.common.collect.Iterables;
+import com.google.datastore.v1.client.DatastoreFactory;
+import com.google.datastore.v1.client.DatastoreOptions;
+import com.google.protobuf.Message;
+import com.google.rpc.Code;
+import com.google.rpc.Status;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.List;
+
+/** Fake Datastore factory used for testing purposes when a true Datastore service is not needed. */
+public class MockDatastoreFactory extends DatastoreFactory {
+ private int nextStatus;
+ private Message nextResponse;
+ private Status nextError;
+ private IOException nextException;
+
+ private String lastPath;
+ private String lastMimeType;
+ private byte[] lastBody;
+ private List lastCookies;
+ private String lastApiFormatHeaderValue;
+
+ public void setNextResponse(Message response) {
+ nextStatus = HttpStatusCodes.STATUS_CODE_OK;
+ nextResponse = response;
+ nextError = null;
+ nextException = null;
+ }
+
+ public void setNextError(int status, Code code, String message) {
+ nextStatus = status;
+ nextResponse = null;
+ nextError = makeErrorContent(message, code);
+ nextException = null;
+ }
+
+ public void setNextException(IOException exception) {
+ nextStatus = 0;
+ nextResponse = null;
+ nextError = null;
+ nextException = exception;
+ }
+
+ @Override
+ public HttpRequestFactory makeClient(DatastoreOptions options) {
+ HttpTransport transport =
+ new MockHttpTransport() {
+ @Override
+ public LowLevelHttpRequest buildRequest(String method, String url) {
+ return new MockLowLevelHttpRequest(url) {
+ @Override
+ public LowLevelHttpResponse execute() throws IOException {
+ lastPath = new GenericUrl(getUrl()).getRawPath();
+ lastMimeType = getContentType();
+ lastCookies = getHeaderValues("Cookie");
+ lastApiFormatHeaderValue =
+ Iterables.getOnlyElement(getHeaderValues("X-Goog-Api-Format-Version"));
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ getStreamingContent().writeTo(out);
+ lastBody = out.toByteArray();
+ if (nextException != null) {
+ throw nextException;
+ }
+ MockLowLevelHttpResponse response =
+ new MockLowLevelHttpResponse()
+ .setStatusCode(nextStatus)
+ .setContentType("application/x-protobuf");
+ if (nextError != null) {
+ checkState(nextResponse == null);
+ response.setContent(new TestableByteArrayInputStream(nextError.toByteArray()));
+ } else {
+ response.setContent(new TestableByteArrayInputStream(nextResponse.toByteArray()));
+ }
+ return response;
+ }
+ };
+ }
+ };
+ Credential credential = options.getCredential();
+ return transport.createRequestFactory(credential);
+ }
+
+ public String getLastPath() {
+ return lastPath;
+ }
+
+ public String getLastMimeType() {
+ return lastMimeType;
+ }
+
+ public String getLastApiFormatHeaderValue() {
+ return lastApiFormatHeaderValue;
+ }
+
+ public byte[] getLastBody() {
+ return lastBody;
+ }
+
+ public List getLastCookies() {
+ return lastCookies;
+ }
+
+ private static Status makeErrorContent(String message, Code code) {
+ return Status.newBuilder().setCode(code.getNumber()).setMessage(message).build();
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/main/resources/META-INF/native-image/native-image.properties b/java-datastore/datastore-v1-proto-client/src/main/resources/META-INF/native-image/native-image.properties
new file mode 100644
index 000000000000..0b5b2e18cb09
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/resources/META-INF/native-image/native-image.properties
@@ -0,0 +1 @@
+Args = --enable-url-protocols=https,http
\ No newline at end of file
diff --git a/java-datastore/datastore-v1-proto-client/src/main/resources/META-INF/native-image/reflect-config.json b/java-datastore/datastore-v1-proto-client/src/main/resources/META-INF/native-image/reflect-config.json
new file mode 100644
index 000000000000..17876ff433eb
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/main/resources/META-INF/native-image/reflect-config.json
@@ -0,0 +1,33 @@
+[
+ {
+ "name":"com.google.datastore.v1.client.Datastore",
+ "methods":[
+ {"name":"allocateIds","parameterTypes":["com.google.datastore.v1.AllocateIdsRequest"] },
+ {"name":"beginTransaction","parameterTypes":["com.google.datastore.v1.BeginTransactionRequest"] },
+ {"name":"commit","parameterTypes":["com.google.datastore.v1.CommitRequest"] },
+ {"name":"lookup","parameterTypes":["com.google.datastore.v1.LookupRequest"] },
+ {"name":"reserveIds","parameterTypes":["com.google.datastore.v1.ReserveIdsRequest"] },
+ {"name":"rollback","parameterTypes":["com.google.datastore.v1.RollbackRequest"] },
+ {"name":"runQuery","parameterTypes":["com.google.datastore.v1.RunQueryRequest"] },
+ {"name":"runAggregationQuery","parameterTypes":["com.google.datastore.v1.RunAggregationQueryRequest"] }
+ ]
+ },
+ {
+ "name":"com.google.api.client.http.HttpRequest",
+ "allDeclaredFields":true,
+ "allPublicFields":true,
+ "allDeclaredMethods":true,
+ "allPublicMethods":true,
+ "allDeclaredConstructors" : true,
+ "allPublicConstructors" : true
+ },
+ {
+ "name":"com.google.api.client.http.HttpHeaders",
+ "allDeclaredFields":true,
+ "allPublicFields":true,
+ "allDeclaredMethods":true,
+ "allPublicMethods":true,
+ "allDeclaredConstructors" : true,
+ "allPublicConstructors" : true
+ }
+]
\ No newline at end of file
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/ChecksumEnforcingInputStreamTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/ChecksumEnforcingInputStreamTest.java
new file mode 100644
index 000000000000..74ab41de0d5f
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/ChecksumEnforcingInputStreamTest.java
@@ -0,0 +1,103 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.fail;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Test for {@link ChecksumEnforcingInputStream}. */
+@RunWith(JUnit4.class)
+public class ChecksumEnforcingInputStreamTest {
+ public void test(int payloadSize) throws Exception {
+ // read 1000 bytes at a time
+ // Since checksum should be correct, do not expect IOException
+ try (ChecksumEnforcingInputStream testInstance = setUpData(payloadSize)) {
+ byte[] buf = new byte[1000];
+ while (testInstance.read(buf, 0, 1000) != -1) {
+ // do nothing with the bytes read
+ }
+ } catch (IOException e) {
+ fail("checksum verification failed! " + e.getMessage());
+ }
+ }
+
+ @Test
+ public void read_withValidChecksum_differentPayloadSizes() throws Exception {
+ // test with various payload sizes (1, 2, 2**2, 2**3 etc upto 2**28 = 256MB)
+ for (int i = 0, payloadSize = 1; i < 29; i++) {
+ long start = System.currentTimeMillis();
+ test(payloadSize);
+ payloadSize *= 2;
+ long duration = System.currentTimeMillis() - start;
+ // log test duration times for bigger payloads
+ if (i > 20) {
+ System.out.println("Test duration for payloadsize = 2** " + i + " is: " + duration + "ms");
+ }
+ }
+ }
+
+ @Test
+ public void read_withInvalidChecksum() {
+ // build a test instance with invalidchecksum
+ // read 1000 bytes at a time
+ // Since checksum should be correct, do not expect IOException
+ try (ChecksumEnforcingInputStream instance =
+ new ChecksumEnforcingInputStream(
+ new ByteArrayInputStream("hello there".getBytes(UTF_8)), "this checksum is invalid")) {
+ byte[] buf = new byte[1000];
+ while (instance.read(buf, 0, 1000) != -1) {
+ // do nothing with the bytes read
+ }
+ } catch (IOException e) {
+ // this is expected
+ return;
+ }
+ fail("should have failed");
+ }
+
+ @Test
+ public void markNotSupported() throws Exception {
+ try (ChecksumEnforcingInputStream testInstance = setUpData(1)) {
+ assertFalse(testInstance.markSupported());
+ }
+ }
+
+ private ChecksumEnforcingInputStream setUpData(int payloadSize) throws Exception {
+ // setup a String of size = input param: payloadSize
+ String str = "This is a repeating string.";
+ String payload;
+ if (payloadSize > str.length()) {
+ int num = payloadSize / str.length();
+ StringBuilder buf = new StringBuilder();
+ for (int i = 0; i < num; i++) {
+ buf.append(str);
+ }
+ payload = buf.toString();
+ } else {
+ payload = str.substring(0, payloadSize);
+ }
+ byte[] bytes = payload.getBytes(UTF_8);
+ String expectedChecksum = EndToEndChecksumHandler.computeChecksum(bytes);
+ return new ChecksumEnforcingInputStream(new ByteArrayInputStream(bytes), expectedChecksum);
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreClientTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreClientTest.java
new file mode 100644
index 000000000000..b2fe1ee90afa
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreClientTest.java
@@ -0,0 +1,407 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static com.google.common.truth.Truth.assertThat;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.fail;
+
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpRequestInitializer;
+import com.google.datastore.v1.AllocateIdsRequest;
+import com.google.datastore.v1.AllocateIdsResponse;
+import com.google.datastore.v1.BeginTransactionRequest;
+import com.google.datastore.v1.BeginTransactionResponse;
+import com.google.datastore.v1.CommitRequest;
+import com.google.datastore.v1.CommitResponse;
+import com.google.datastore.v1.EntityResult;
+import com.google.datastore.v1.LookupRequest;
+import com.google.datastore.v1.LookupResponse;
+import com.google.datastore.v1.QueryResultBatch;
+import com.google.datastore.v1.ReserveIdsRequest;
+import com.google.datastore.v1.ReserveIdsResponse;
+import com.google.datastore.v1.RollbackRequest;
+import com.google.datastore.v1.RollbackResponse;
+import com.google.datastore.v1.RunAggregationQueryRequest;
+import com.google.datastore.v1.RunAggregationQueryResponse;
+import com.google.datastore.v1.RunQueryRequest;
+import com.google.datastore.v1.RunQueryResponse;
+import com.google.datastore.v1.client.testing.MockCredential;
+import com.google.datastore.v1.client.testing.MockDatastoreFactory;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.Message;
+import com.google.rpc.Code;
+import java.io.IOException;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.net.SocketTimeoutException;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link DatastoreFactory} and {@link Datastore}. */
+@RunWith(JUnit4.class)
+public class DatastoreClientTest {
+ private static final String PROJECT_ID = "project-id";
+
+ private DatastoreFactory factory = new MockDatastoreFactory();
+ private DatastoreOptions.Builder options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).credential(new MockCredential());
+
+ @Test
+ public void options_NoProjectIdOrProjectEndpoint() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> factory.create(new DatastoreOptions.Builder().build()));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Either project ID or project endpoint must be provided");
+ factory.create(options.build());
+ }
+
+ @Test
+ public void options_ProjectIdAndProjectEndpoint() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .projectEndpoint(
+ "http://localhost:1234/datastore/v1beta42/projects/project-id"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Cannot set both project endpoint and project ID");
+ }
+
+ @Test
+ public void options_LocalHostAndProjectEndpoint() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .localHost("localhost:8080")
+ .projectEndpoint(
+ "http://localhost:1234/datastore/v1beta42/projects/project-id"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Can set at most one of project endpoint, host, and local host");
+ }
+
+ @Test
+ public void options_HostAndProjectEndpoint() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .host("foo-datastore.googleapis.com")
+ .projectEndpoint(
+ "http://localhost:1234/datastore/v1beta42/projects/project-id"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Can set at most one of project endpoint, host, and local host");
+ }
+
+ @Test
+ public void options_HostAndLocalHost() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .host("foo-datastore.googleapis.com")
+ .localHost("localhost:8080"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Can set at most one of project endpoint, host, and local host");
+ }
+
+ @Test
+ public void options_InvalidLocalHost() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .localHost("!not a valid url!")
+ .build()));
+ assertThat(exception).hasMessageThat().contains("Illegal character");
+ }
+
+ @Test
+ public void options_SchemeInLocalHost() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> new DatastoreOptions.Builder().localHost("http://localhost:8080"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Local host \"http://localhost:8080\" must not include scheme");
+ }
+
+ @Test
+ public void options_InvalidHost() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .host("!not a valid url!")
+ .build()));
+ assertThat(exception).hasMessageThat().contains("Illegal character");
+ }
+
+ @Test
+ public void options_SchemeInHost() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> new DatastoreOptions.Builder().host("http://foo-datastore.googleapis.com"));
+
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Host \"http://foo-datastore.googleapis.com\" must not include scheme.");
+ }
+
+ @Test
+ public void create_NullOptions() throws Exception {
+ assertThrows(NullPointerException.class, () -> factory.create(null));
+ }
+
+ @Test
+ public void create_Host() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .host("foo-datastore.googleapis.com")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("https://foo-datastore.googleapis.com/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_LocalHost() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .localHost("localhost:8080")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("http://localhost:8080/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_LocalHostIp() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .localHost("127.0.0.1:8080")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("http://127.0.0.1:8080/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_DefaultHost() {
+ Datastore datastore =
+ factory.create(new DatastoreOptions.Builder().projectId(PROJECT_ID).build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("https://datastore.googleapis.com/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_ProjectEndpoint() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectEndpoint("http://prom-qa/datastore/v1beta42/projects/project-id")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("http://prom-qa/datastore/v1beta42/projects/project-id");
+ }
+
+ @Test
+ public void create_ProjectEndpointNoScheme() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectEndpoint("localhost:1234/datastore/v1beta42/projects/project-id")
+ .build()));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains(
+ "Project endpoint \"localhost:1234/datastore/v1beta42/projects/project-id\" must"
+ + " include scheme.");
+ }
+
+ @Test
+ public void initializer() throws Exception {
+ options.initializer(
+ new HttpRequestInitializer() {
+ @Override
+ public void initialize(HttpRequest request) {
+ request.getHeaders().setCookie("magic");
+ }
+ });
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+ AllocateIdsRequest request = AllocateIdsRequest.newBuilder().build();
+ AllocateIdsResponse response = AllocateIdsResponse.newBuilder().build();
+ mockClient.setNextResponse(response);
+ assertEquals(response, datastore.allocateIds(request));
+ assertEquals("magic", mockClient.getLastCookies().get(0));
+ }
+
+ @Test
+ public void allocateIds() throws Exception {
+ AllocateIdsRequest.Builder request = AllocateIdsRequest.newBuilder();
+ AllocateIdsResponse.Builder response = AllocateIdsResponse.newBuilder();
+ expectRpc("allocateIds", request.build(), response.build());
+ }
+
+ @Test
+ public void lookup() throws Exception {
+ LookupRequest.Builder request = LookupRequest.newBuilder();
+ LookupResponse.Builder response = LookupResponse.newBuilder();
+ expectRpc("lookup", request.build(), response.build());
+ }
+
+ @Test
+ public void beginTransaction() throws Exception {
+ BeginTransactionRequest.Builder request = BeginTransactionRequest.newBuilder();
+ BeginTransactionResponse.Builder response = BeginTransactionResponse.newBuilder();
+ response.setTransaction(ByteString.copyFromUtf8("project-id"));
+ expectRpc("beginTransaction", request.build(), response.build());
+ }
+
+ @Test
+ public void commit() throws Exception {
+ CommitRequest.Builder request = CommitRequest.newBuilder();
+ request.setTransaction(ByteString.copyFromUtf8("project-id"));
+ CommitResponse.Builder response = CommitResponse.newBuilder();
+ expectRpc("commit", request.build(), response.build());
+ }
+
+ @Test
+ public void reserveIds() throws Exception {
+ ReserveIdsRequest.Builder request = ReserveIdsRequest.newBuilder();
+ ReserveIdsResponse.Builder response = ReserveIdsResponse.newBuilder();
+ expectRpc("reserveIds", request.build(), response.build());
+ }
+
+ @Test
+ public void rollback() throws Exception {
+ RollbackRequest.Builder request = RollbackRequest.newBuilder();
+ request.setTransaction(ByteString.copyFromUtf8("project-id"));
+ RollbackResponse.Builder response = RollbackResponse.newBuilder();
+ expectRpc("rollback", request.build(), response.build());
+ }
+
+ @Test
+ public void runQuery() throws Exception {
+ RunQueryRequest.Builder request = RunQueryRequest.newBuilder();
+ request.getQueryBuilder();
+ RunQueryResponse.Builder response = RunQueryResponse.newBuilder();
+ response
+ .getBatchBuilder()
+ .setEntityResultType(EntityResult.ResultType.FULL)
+ .setMoreResults(QueryResultBatch.MoreResultsType.NOT_FINISHED);
+ expectRpc("runQuery", request.build(), response.build());
+ }
+
+ @Test
+ public void runAggregationQuery() throws Exception {
+ RunAggregationQueryRequest.Builder request = RunAggregationQueryRequest.newBuilder();
+ RunAggregationQueryResponse.Builder response = RunAggregationQueryResponse.newBuilder();
+ expectRpc("runAggregationQuery", request.build(), response.build());
+ }
+
+ private void expectRpc(String methodName, Message request, Message response) throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ mockClient.setNextResponse(response);
+ @SuppressWarnings("rawtypes")
+ Class[] methodArgs = {request.getClass()};
+ Method call = Datastore.class.getMethod(methodName, methodArgs);
+ Object[] callArgs = {request};
+ assertEquals(response, call.invoke(datastore, callArgs));
+
+ assertEquals("/v1/projects/project-id:" + methodName, mockClient.getLastPath());
+ assertEquals("application/x-protobuf", mockClient.getLastMimeType());
+ assertEquals("2", mockClient.getLastApiFormatHeaderValue());
+ assertArrayEquals(request.toByteArray(), mockClient.getLastBody());
+ assertEquals(1, datastore.getRpcCount());
+
+ datastore.resetRpcCount();
+ assertEquals(0, datastore.getRpcCount());
+
+ mockClient.setNextError(400, Code.INVALID_ARGUMENT, "oops");
+ try {
+ call.invoke(datastore, callArgs);
+ fail();
+ } catch (InvocationTargetException targetException) {
+ DatastoreException exception = (DatastoreException) targetException.getCause();
+ assertEquals(Code.INVALID_ARGUMENT, exception.getCode());
+ assertEquals(methodName, exception.getMethodName());
+ assertEquals("oops", exception.getMessage());
+ }
+
+ SocketTimeoutException socketTimeoutException = new SocketTimeoutException("ste");
+ mockClient.setNextException(socketTimeoutException);
+ try {
+ call.invoke(datastore, callArgs);
+ fail();
+ } catch (InvocationTargetException targetException) {
+ DatastoreException exception = (DatastoreException) targetException.getCause();
+ assertEquals(Code.DEADLINE_EXCEEDED, exception.getCode());
+ assertEquals(methodName, exception.getMethodName());
+ assertEquals("Deadline exceeded", exception.getMessage());
+ assertSame(socketTimeoutException, exception.getCause());
+ }
+
+ IOException ioException = new IOException("ioe");
+ mockClient.setNextException(ioException);
+ try {
+ call.invoke(datastore, callArgs);
+ fail();
+ } catch (InvocationTargetException targetException) {
+ DatastoreException exception = (DatastoreException) targetException.getCause();
+ assertEquals(Code.UNAVAILABLE, exception.getCode());
+ assertEquals(methodName, exception.getMethodName());
+ assertEquals("I/O error", exception.getMessage());
+ assertSame(ioException, exception.getCause());
+ }
+
+ assertEquals(3, datastore.getRpcCount());
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreEmulatorTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreEmulatorTest.java
new file mode 100644
index 000000000000..d03cfa867fab
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreEmulatorTest.java
@@ -0,0 +1,99 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static org.junit.Assert.fail;
+
+import java.util.List;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link DatastoreEmulator}. */
+@RunWith(JUnit4.class)
+public class DatastoreEmulatorTest {
+
+ private static final DatastoreEmulatorOptions options =
+ new DatastoreEmulatorOptions.Builder().build();
+
+ @Test
+ public void testArgs() throws DatastoreEmulatorException {
+ DatastoreEmulator datastore =
+ new DatastoreEmulator(null, "blar", options) {
+ @Override
+ void startEmulatorInternal(
+ String emulatorDir, String projectId, List cmdLineOpts) {
+ // no-op for testing
+ }
+ };
+
+ try {
+ datastore.start(null, "projectId");
+ fail("expected exception");
+ } catch (NullPointerException npe) {
+ // good
+ }
+
+ try {
+ datastore.start("path/to/emulator", null);
+ fail("expected exception");
+ } catch (NullPointerException npe) {
+ // good
+ }
+
+ datastore.start("path/to/emulator", "projectId");
+ }
+
+ @Test
+ public void testLifecycle() throws DatastoreEmulatorException {
+ DatastoreEmulator datastore =
+ new DatastoreEmulator(null, "blar", options) {
+ @Override
+ void startEmulatorInternal(
+ String emulatorDir, String projectId, List cmdLineOpts) {
+ // no-op for testing
+ }
+
+ @Override
+ protected void stopEmulatorInternal() {
+ // no-op for testing
+ }
+ };
+
+ String emulatorDir = "/yar";
+ String myProject = "myproject";
+
+ datastore.start(emulatorDir, myProject);
+ try {
+ datastore.start(emulatorDir, myProject);
+ fail("expected exception");
+ } catch (IllegalStateException e) {
+ // good
+ }
+
+ datastore.stop();
+ // It's ok to stop if we've already stopped.
+ datastore.stop();
+
+ // Once we've stopped we can't start again.
+ try {
+ datastore.start(emulatorDir, myProject);
+ fail("expected exception");
+ } catch (IllegalStateException e) {
+ // good
+ }
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreFactoryTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreFactoryTest.java
new file mode 100644
index 000000000000..bc28342c092f
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreFactoryTest.java
@@ -0,0 +1,93 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertTrue;
+
+import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
+import com.google.api.client.http.HttpRequestFactory;
+import com.google.api.client.http.javanet.NetHttpTransport;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Test for {@link DatastoreFactory}. */
+@RunWith(JUnit4.class)
+public class DatastoreFactoryTest {
+ private static final String PROJECT_ID = "project-id";
+
+ private DatastoreFactory factory = DatastoreFactory.get();
+
+ /**
+ * Without specifying a credential or transport, the factory will create a default transport on
+ * its own.
+ */
+ @Test
+ public void makeClient_Default() {
+ DatastoreOptions options = new DatastoreOptions.Builder().projectId(PROJECT_ID).build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertNotNull(f.getTransport());
+ assertTrue(f.getTransport() instanceof NetHttpTransport);
+ }
+
+ /**
+ * Specifying a credential, but not a transport, the factory will use the transport from the
+ * credential.
+ */
+ @Test
+ public void makeClient_WithCredential() {
+ NetHttpTransport transport = new NetHttpTransport();
+ GoogleCredential credential = new GoogleCredential.Builder().setTransport(transport).build();
+ DatastoreOptions options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).credential(credential).build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertEquals(transport, f.getTransport());
+ }
+
+ /** Specifying a transport, but not a credential, the factory will use the transport specified. */
+ @Test
+ public void makeClient_WithTransport() {
+ NetHttpTransport transport = new NetHttpTransport();
+ DatastoreOptions options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).transport(transport).build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertEquals(transport, f.getTransport());
+ }
+
+ /**
+ * Specifying both credential and transport, the factory will use the transport specified and not
+ * the one in the credential.
+ */
+ @Test
+ public void makeClient_WithCredentialTransport() {
+ NetHttpTransport credTransport = new NetHttpTransport();
+ NetHttpTransport transport = new NetHttpTransport();
+ GoogleCredential credential =
+ new GoogleCredential.Builder().setTransport(credTransport).build();
+ DatastoreOptions options =
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .credential(credential)
+ .transport(transport)
+ .build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertNotSame(credTransport, f.getTransport());
+ assertEquals(transport, f.getTransport());
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreHelperTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreHelperTest.java
new file mode 100644
index 000000000000..d9f5979c317d
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/DatastoreHelperTest.java
@@ -0,0 +1,320 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static com.google.datastore.v1.client.DatastoreHelper.getByteString;
+import static com.google.datastore.v1.client.DatastoreHelper.makeKey;
+import static com.google.datastore.v1.client.DatastoreHelper.makeValue;
+import static com.google.datastore.v1.client.DatastoreHelper.toDate;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
+
+import com.google.datastore.v1.Key;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Value;
+import com.google.datastore.v1.Value.ValueTypeCase;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.Timestamp;
+import java.util.Date;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link DatastoreHelper}. */
+@RunWith(JUnit4.class)
+public class DatastoreHelperTest {
+
+ private static final Key PARENT =
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Parent").setId(23L)).build();
+ private static final Key GRANDPARENT =
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Grandparent").setId(24L))
+ .build();
+ private static final Key CHILD =
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Child").setId(26L)).build();
+
+ @Test
+ public void testMakeKey_BadTypeForKind() {
+ try {
+ DatastoreHelper.makeKey(new Object());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+
+ @Test
+ public void testMakeKey_BadTypeForNameId() {
+ try {
+ DatastoreHelper.makeKey("kind", new Object());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+
+ @Test
+ public void testMakeKey_Empty() {
+ assertEquals(Key.newBuilder().build(), DatastoreHelper.makeKey().build());
+ }
+
+ @Test
+ public void testMakeKey_Incomplete() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo")).build(),
+ makeKey("Foo").build());
+ }
+
+ @Test
+ public void testMakeKey_IdInt() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setId(1)).build(),
+ makeKey("Foo", 1).build());
+ }
+
+ @Test
+ public void testMakeKey_IdLong() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setId(1)).build(),
+ makeKey("Foo", 1L).build());
+ }
+
+ @Test
+ public void testMakeKey_IdShort() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setId(1)).build(),
+ makeKey("Foo", (short) 1).build());
+ }
+
+ @Test
+ public void testMakeKey_Name() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setName("hi")).build(),
+ makeKey("Foo", "hi").build());
+ }
+
+ @Test
+ public void testMakeKey_KindNameKind() {
+ assertEquals(
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Foo").setName("hi"))
+ .addPath(Key.PathElement.newBuilder().setKind("Bar"))
+ .build(),
+ makeKey("Foo", "hi", "Bar").build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKind() {
+ // 1 key at the beginning of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(PARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Child"))
+ .build(),
+ makeKey(PARENT, "Child").build());
+ }
+
+ @Test
+ public void testMakeKey_KindIdKeyKind() {
+ // 1 key in the middle of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Grandparent").setId(24L))
+ .addPath(PARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Child"))
+ .build(),
+ makeKey("Grandparent", 24L, PARENT, "Child").build());
+ }
+
+ @Test
+ public void testMakeKey_KindIdKey() {
+ // 1 key at the end of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Grandparent").setId(24L))
+ .addPath(PARENT.getPath(0))
+ .build(),
+ makeKey("Grandparent", 24L, PARENT).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKindIdKey() {
+ // 1 key at the beginning and 1 key at the end of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Parent").setId(23L))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(GRANDPARENT, "Parent", 23, CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_Key() {
+ // Just 1 key
+ assertEquals(Key.newBuilder().addPath(CHILD.getPath(0)).build(), makeKey(CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKey() {
+ // Just 2 keys
+ assertEquals(
+ Key.newBuilder().addPath(PARENT.getPath(0)).addPath(CHILD.getPath(0)).build(),
+ makeKey(PARENT, CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKeyKey() {
+ // Just 3 keys
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(GRANDPARENT, PARENT, CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyMultiLevelKey() {
+ // 1 key with 2 elements
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(GRANDPARENT, makeKey(PARENT, CHILD).build()).build());
+ }
+
+ @Test
+ public void testMakeKey_MultiLevelKeyKey() {
+ // 1 key with 2 elements
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(makeKey(GRANDPARENT, PARENT).build(), CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_MultiLevelKey() {
+ // 1 key with 3 elements
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(makeKey(GRANDPARENT, PARENT, CHILD).build()).build());
+ }
+
+ @Test
+ public void testMakeKey_PartitionId() {
+ PartitionId partitionId = PartitionId.newBuilder().setNamespaceId("namespace-id").build();
+ Key parent = PARENT.toBuilder().setPartitionId(partitionId).build();
+ assertEquals(
+ Key.newBuilder()
+ .setPartitionId(partitionId)
+ .addPath(PARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Child"))
+ .build(),
+ makeKey(parent, "Child").build());
+ }
+
+ @Test
+ public void testMakeKey_NonMatchingPartitionId2() {
+ PartitionId partitionId1 = PartitionId.newBuilder().setNamespaceId("namespace-id").build();
+ PartitionId partitionId2 =
+ PartitionId.newBuilder().setNamespaceId("another-namespace-id").build();
+ try {
+ makeKey(
+ PARENT.toBuilder().setPartitionId(partitionId1).build(),
+ CHILD.toBuilder().setPartitionId(partitionId2).build());
+ fail("expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+
+ @Test
+ public void testMakeTimestampValue() throws Exception {
+ // Test cases with nanos == 0.
+ assertConversion(-50_000, -50, 0);
+ assertConversion(-1_000, -1, 0);
+ assertConversion(0, 0, 0);
+ assertConversion(1_000, 1, 0);
+ assertConversion(2_000, 2, 0);
+ assertConversion(100_000, 100, 0);
+
+ // Test cases with nanos % 1_000_000 == 0 (no loss of precision).
+ assertConversion(2, 0, 2_000_000);
+ assertConversion(1_003, 1, 3_000_000);
+ assertConversion(2_005, 2, 5_000_000);
+
+ // Timestamp specification requires that nanos >= 0 even if the timestamp
+ // is before the epoch.
+ assertConversion(0, 0, 0);
+ assertConversion(-250, -1, 750_000_000); // 1/4 second before epoch
+ assertConversion(-500, -1, 500_000_000); // 1/2 second before epoch
+ assertConversion(-750, -1, 250_000_000); // 3/4 second before epoch
+
+ // If nanos % 1_000_000 != 0, precision is lost (via truncation) when
+ // converting to milliseconds.
+ assertTimestampToMilliseconds(3_100, 3, 100_000_999);
+ assertMillisecondsToTimestamp(3_100, 3, 100_000_000);
+ assertTimestampToMilliseconds(5_999, 5, 999_999_999);
+ assertMillisecondsToTimestamp(5_999, 5, 999_000_000);
+ assertTimestampToMilliseconds(7_100, 7, 100_000_001);
+ assertMillisecondsToTimestamp(7_100, 7, 100_000_000);
+ }
+
+ private void assertConversion(long millis, long seconds, int nanos) {
+ assertMillisecondsToTimestamp(millis, seconds, nanos);
+ assertTimestampToMilliseconds(millis, seconds, nanos);
+ }
+
+ private void assertMillisecondsToTimestamp(long millis, long seconds, long nanos) {
+ Value timestampValue = makeValue(new Date(millis)).build();
+ assertEquals(ValueTypeCase.TIMESTAMP_VALUE, timestampValue.getValueTypeCase());
+ assertEquals(seconds, timestampValue.getTimestampValue().getSeconds());
+ assertEquals(nanos, timestampValue.getTimestampValue().getNanos());
+ }
+
+ private void assertTimestampToMilliseconds(long millis, long seconds, int nanos) {
+ Value.Builder value =
+ Value.newBuilder()
+ .setTimestampValue(Timestamp.newBuilder().setSeconds(seconds).setNanos(nanos));
+ assertEquals(millis, DatastoreHelper.toDate(value.build()).getTime());
+ }
+
+ @Test
+ public void testProjectionHandling() {
+ assertEquals(
+ ByteString.copyFromUtf8("hi"), getByteString(makeValue("hi").setMeaning(18).build()));
+ try {
+ getByteString(makeValue("hi").build());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+
+ assertEquals(new Date(1), toDate(makeValue(1000).setMeaning(18).build()));
+ try {
+ toDate(makeValue(1000).build());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/EndToEndChecksumHandlerTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/EndToEndChecksumHandlerTest.java
new file mode 100644
index 000000000000..09176678e18a
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/EndToEndChecksumHandlerTest.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Test for {@link EndToEndChecksumHandler}. */
+@RunWith(JUnit4.class)
+public class EndToEndChecksumHandlerTest {
+ private final byte[] payloadBytes =
+ "This is a long string with numbers 1234, 134.56 ".getBytes(UTF_8);
+ private final byte[] payloadForUnsignedLongChecksum = "aaa".getBytes(UTF_8);
+ private final String unsignedLongChecksum = "3818383321";
+
+ @Test
+ public void validateChecksum_correctChecksum() {
+ String computed = EndToEndChecksumHandler.computeChecksum(payloadBytes);
+ assertTrue(EndToEndChecksumHandler.validateChecksum(computed, payloadBytes));
+ }
+
+ @Test
+ public void computeChecksum_returnsUnsignedLongAsStringValue() {
+ String computed = EndToEndChecksumHandler.computeChecksum(payloadForUnsignedLongChecksum);
+ assertEquals("computeChecksum return value", unsignedLongChecksum, computed);
+ }
+
+ @Test
+ public void validateChecksum_incorrectChecksum() {
+ String computed = EndToEndChecksumHandler.computeChecksum("random string".getBytes(UTF_8));
+ assertFalse(EndToEndChecksumHandler.validateChecksum(computed, payloadBytes));
+ }
+
+ @Test
+ public void validateChecksum_nullChecksum() {
+ assertFalse(EndToEndChecksumHandler.validateChecksum(null, payloadBytes));
+ }
+
+ @Test
+ public void validateChecksum_emptyChecksum() {
+ assertFalse(EndToEndChecksumHandler.validateChecksum("", payloadBytes));
+ }
+
+ @Test
+ public void validateChecksum_nullPayload() {
+ assertFalse(EndToEndChecksumHandler.validateChecksum("foo", null));
+ }
+
+ @Test
+ public void validateChecksum_emptyPayload() {
+ assertFalse(EndToEndChecksumHandler.validateChecksum("foo", new byte[0]));
+ }
+
+ @Test
+ public void computeChecksum_nullInputBytes() {
+ assertNull(EndToEndChecksumHandler.computeChecksum(null));
+ }
+
+ @Test
+ public void computeChecksum_emptyArrayForInputBytes() {
+ assertNull(EndToEndChecksumHandler.computeChecksum(new byte[0]));
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/QuerySplitterTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/QuerySplitterTest.java
new file mode 100644
index 000000000000..027029a768af
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/QuerySplitterTest.java
@@ -0,0 +1,369 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static com.google.common.truth.Truth.assertThat;
+import static com.google.datastore.v1.client.DatastoreHelper.makeAndFilter;
+import static com.google.datastore.v1.client.DatastoreHelper.makeFilter;
+import static com.google.datastore.v1.client.DatastoreHelper.makeKey;
+import static com.google.datastore.v1.client.DatastoreHelper.makeOrder;
+import static com.google.datastore.v1.client.DatastoreHelper.makePropertyReference;
+import static com.google.datastore.v1.client.DatastoreHelper.makeValue;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertThrows;
+
+import com.google.datastore.v1.Entity;
+import com.google.datastore.v1.EntityResult;
+import com.google.datastore.v1.EntityResult.ResultType;
+import com.google.datastore.v1.Filter;
+import com.google.datastore.v1.Key;
+import com.google.datastore.v1.KindExpression;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Projection;
+import com.google.datastore.v1.PropertyFilter.Operator;
+import com.google.datastore.v1.PropertyOrder.Direction;
+import com.google.datastore.v1.Query;
+import com.google.datastore.v1.QueryResultBatch;
+import com.google.datastore.v1.QueryResultBatch.MoreResultsType;
+import com.google.datastore.v1.ReadOptions;
+import com.google.datastore.v1.RunQueryRequest;
+import com.google.datastore.v1.RunQueryResponse;
+import com.google.datastore.v1.client.testing.MockCredential;
+import com.google.datastore.v1.client.testing.MockDatastoreFactory;
+import com.google.protobuf.Int32Value;
+import com.google.protobuf.Timestamp;
+import java.util.List;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link QuerySplitterImpl}. */
+@RunWith(JUnit4.class)
+public class QuerySplitterTest {
+ private static final String PROJECT_ID = "project-id";
+ private static final PartitionId PARTITION =
+ PartitionId.newBuilder().setProjectId(PROJECT_ID).build();
+ private static final String KIND = "test-kind";
+
+ private DatastoreFactory factory = new MockDatastoreFactory();
+ private DatastoreOptions.Builder options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).credential(new MockCredential());
+
+ private Filter propertyFilter = makeFilter("foo", Operator.EQUAL, makeValue("value")).build();
+
+ private Query query =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .setFilter(propertyFilter)
+ .build();
+
+ private Query splitQuery =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .addOrder(makeOrder("__scatter__", Direction.ASCENDING))
+ .addProjection(Projection.newBuilder().setProperty(makePropertyReference("__key__")))
+ .build();
+
+ private Key splitKey0 = makeKey(KIND, String.format("%05d", 1)).setPartitionId(PARTITION).build();
+ private Key splitKey1 =
+ makeKey(KIND, String.format("%05d", 101)).setPartitionId(PARTITION).build();
+ private Key splitKey2 =
+ makeKey(KIND, String.format("%05d", 201)).setPartitionId(PARTITION).build();
+ private Key splitKey3 =
+ makeKey(KIND, String.format("%05d", 301)).setPartitionId(PARTITION).build();
+
+ @Test
+ public void disallowsSortOrder() {
+ Datastore datastore = factory.create(options.build());
+ Query queryWithOrder =
+ query.toBuilder().addOrder(makeOrder("bar", Direction.ASCENDING)).build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> QuerySplitterImpl.INSTANCE.getSplits(queryWithOrder, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query cannot have any sort orders.");
+ }
+
+ @Test
+ public void disallowsMultipleKinds() {
+ Datastore datastore = factory.create(options.build());
+ Query queryWithMultipleKinds =
+ query.toBuilder()
+ .addKind(KindExpression.newBuilder().setName("another-kind").build())
+ .build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ QuerySplitterImpl.INSTANCE.getSplits(
+ queryWithMultipleKinds, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query must have exactly one kind.");
+ }
+
+ @Test
+ public void disallowsKindlessQuery() {
+ Datastore datastore = factory.create(options.build());
+ Query kindlessQuery = query.toBuilder().clearKind().build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> QuerySplitterImpl.INSTANCE.getSplits(kindlessQuery, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query must have exactly one kind.");
+ }
+
+ @Test
+ public void disallowsInequalityFilter() {
+ Datastore datastore = factory.create(options.build());
+ Query queryWithInequality =
+ query.toBuilder()
+ .setFilter(makeFilter("foo", Operator.GREATER_THAN, makeValue("value")))
+ .build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ QuerySplitterImpl.INSTANCE.getSplits(queryWithInequality, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query cannot have any inequality filters.");
+ }
+
+ @Test
+ public void splitsMustBePositive() {
+ Datastore datastore = factory.create(options.build());
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> QuerySplitterImpl.INSTANCE.getSplits(query, PARTITION, 0, datastore));
+ assertThat(exception).hasMessageThat().contains("The number of splits must be greater than 0.");
+ }
+
+ @Test
+ public void getSplits() throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .addEntityResults(makeKeyOnlyEntity(splitKey1))
+ .addEntityResults(makeKeyOnlyEntity(splitKey2))
+ .addEntityResults(makeKeyOnlyEntity(splitKey3))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ List splittedQueries =
+ QuerySplitterImpl.INSTANCE.getSplits(query, PARTITION, 3, datastore);
+
+ assertThat(splittedQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey1))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey1, splitKey3))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey3, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(PARTITION)
+ .setProjectId(PROJECT_ID)
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(2 * 32).build()))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ @Test
+ public void getSplitsWithDatabaseId() throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ PartitionId partition =
+ PartitionId.newBuilder().setProjectId(PROJECT_ID).setDatabaseId("test-database").build();
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .addEntityResults(makeKeyOnlyEntity(splitKey1))
+ .addEntityResults(makeKeyOnlyEntity(splitKey2))
+ .addEntityResults(makeKeyOnlyEntity(splitKey3))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ List splitQueries = QuerySplitterImpl.INSTANCE.getSplits(query, partition, 3, datastore);
+
+ assertThat(splitQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey1))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey1, splitKey3))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey3, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(partition)
+ .setProjectId(PROJECT_ID)
+ .setDatabaseId("test-database")
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(2 * 32).build()))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ @Test
+ public void notEnoughSplits() throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ List splittedQueries =
+ QuerySplitterImpl.INSTANCE.getSplits(query, PARTITION, 100, datastore);
+
+ assertThat(splittedQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey0))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey0, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(PARTITION)
+ .setProjectId(PROJECT_ID)
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(99 * 32).build()))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ @Test
+ public void getSplits_withReadTime() throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .addEntityResults(makeKeyOnlyEntity(splitKey1))
+ .addEntityResults(makeKeyOnlyEntity(splitKey2))
+ .addEntityResults(makeKeyOnlyEntity(splitKey3))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ Timestamp readTime = Timestamp.newBuilder().setSeconds(1654651341L).build();
+
+ List splittedQueries =
+ QuerySplitterImpl.INSTANCE.getSplits(query, PARTITION, 3, datastore, readTime);
+
+ assertThat(splittedQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey1))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey1, splitKey3))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey3, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(PARTITION)
+ .setProjectId(PROJECT_ID)
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(2 * 32).build()))
+ .setReadOptions(ReadOptions.newBuilder().setReadTime(readTime))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ private static EntityResult makeKeyOnlyEntity(Key key) {
+ return EntityResult.newBuilder().setEntity(Entity.newBuilder().setKey(key).build()).build();
+ }
+
+ private static Filter makeFilterWithKeyRange(Filter originalFilter, Key startKey, Key endKey) {
+ Filter startKeyFilter =
+ startKey == null
+ ? null
+ : makeFilter("__key__", Operator.GREATER_THAN_OR_EQUAL, makeValue(startKey)).build();
+
+ Filter endKeyFilter =
+ endKey == null
+ ? null
+ : makeFilter("__key__", Operator.LESS_THAN, makeValue(endKey)).build();
+
+ if (startKeyFilter == null && endKeyFilter == null) {
+ throw new IllegalArgumentException();
+ }
+
+ if (startKeyFilter != null && endKeyFilter == null) {
+ return makeAndFilter(originalFilter, startKeyFilter).build();
+ }
+
+ if (startKeyFilter == null && endKeyFilter != null) {
+ return makeAndFilter(originalFilter, endKeyFilter).build();
+ }
+
+ return makeAndFilter(originalFilter, startKeyFilter, endKeyFilter).build();
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/RemoteRpcTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/RemoteRpcTest.java
new file mode 100644
index 000000000000..4fad87d26a85
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/RemoteRpcTest.java
@@ -0,0 +1,373 @@
+/*
+ * Copyright 2026 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.datastore.v1.client;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpTransport;
+import com.google.api.client.http.LowLevelHttpRequest;
+import com.google.api.client.http.LowLevelHttpResponse;
+import com.google.api.client.http.protobuf.ProtoHttpContent;
+import com.google.api.client.util.Charsets;
+import com.google.datastore.v1.BeginTransactionResponse;
+import com.google.datastore.v1.RollbackRequest;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.MessageLite;
+import com.google.rpc.Code;
+import com.google.rpc.Status;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.zip.GZIPOutputStream;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Test for {@link RemoteRpc}. */
+@RunWith(JUnit4.class)
+public class RemoteRpcTest {
+
+ private static final String METHOD_NAME = "methodName";
+
+ @Test
+ public void testException() {
+ Status statusProto =
+ Status.newBuilder()
+ .setCode(Code.UNAUTHENTICATED_VALUE)
+ .setMessage("The request does not have valid authentication credentials.")
+ .build();
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream(statusProto.toByteArray()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.UNAUTHENTICATED, exception.getCode());
+ assertEquals(
+ "The request does not have valid authentication credentials.", exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testInvalidProtoException() {
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream("".getBytes()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.INTERNAL, exception.getCode());
+ assertEquals(
+ "Unable to parse Status protocol buffer: HTTP status code was 401.",
+ exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testEmptyProtoException() {
+ Status statusProto = Status.newBuilder().build();
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream(statusProto.toByteArray()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 404);
+ assertEquals(Code.INTERNAL, exception.getCode());
+ assertEquals(
+ "Unexpected OK error code with HTTP status code of 404. Message: .",
+ exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testEmptyProtoExceptionUnauthenticated() {
+ Status statusProto = Status.newBuilder().build();
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream(statusProto.toByteArray()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.UNAUTHENTICATED, exception.getCode());
+ assertEquals("Unauthenticated.", exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testPlainTextException() {
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream("Text Error".getBytes()),
+ "text/plain",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.INTERNAL, exception.getCode());
+ assertEquals(
+ "Non-protobuf error: Text Error. HTTP status code was 401.", exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testGzip() throws IOException, DatastoreException {
+ BeginTransactionResponse response = newBeginTransactionResponse();
+ InjectedTestValues injectedTestValues =
+ new InjectedTestValues(gzip(response), new byte[1], true);
+ RemoteRpc rpc = newRemoteRpc(injectedTestValues);
+
+ InputStream is =
+ rpc.call("beginTransaction", BeginTransactionResponse.getDefaultInstance(), "", "");
+ BeginTransactionResponse parsedResponse = BeginTransactionResponse.parseFrom(is);
+ is.close();
+
+ assertEquals(response, parsedResponse);
+ // Check that the underlying stream is exhausted.
+ assertEquals(-1, injectedTestValues.inputStream.read());
+ }
+
+ @Test
+ public void testHttpHeaders_expectE2eChecksumHeader() throws IOException {
+ // Enable E2E-Checksum system env variable
+ RemoteRpc.setSystemEnvE2EChecksum(true);
+ String projectId = "project-id";
+ MessageLite request =
+ RollbackRequest.newBuilder().setTransaction(ByteString.copyFromUtf8(projectId)).build();
+ RemoteRpc rpc =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest =
+ rpc.getClient().buildPostRequest(rpc.resolveURL("blah"), new ProtoHttpContent(request));
+ rpc.setHeaders(request, httpRequest, projectId, "");
+ assertNotNull(
+ httpRequest.getHeaders().getFirstHeaderStringValue(RemoteRpc.API_FORMAT_VERSION_HEADER));
+ // Expect to find e2e-checksum header
+ String header =
+ httpRequest
+ .getHeaders()
+ .getFirstHeaderStringValue(EndToEndChecksumHandler.HTTP_REQUEST_CHECKSUM_HEADER);
+ assertEquals(9, header.length());
+ }
+
+ @Test
+ public void testHttpHeaders_doNotExpectE2eChecksumHeader() throws IOException {
+ // disable E2E-Checksum system env variable
+ RemoteRpc.setSystemEnvE2EChecksum(false);
+ String projectId = "project-id";
+ MessageLite request =
+ RollbackRequest.newBuilder().setTransaction(ByteString.copyFromUtf8(projectId)).build();
+ RemoteRpc rpc =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest =
+ rpc.getClient().buildPostRequest(rpc.resolveURL("blah"), new ProtoHttpContent(request));
+ rpc.setHeaders(request, httpRequest, projectId, "");
+ assertNotNull(
+ httpRequest.getHeaders().getFirstHeaderStringValue(RemoteRpc.API_FORMAT_VERSION_HEADER));
+ // Do not expect to find e2e-checksum header
+ assertNull(
+ httpRequest
+ .getHeaders()
+ .getFirstHeaderStringValue(EndToEndChecksumHandler.HTTP_REQUEST_CHECKSUM_HEADER));
+ }
+
+ @Test
+ public void testHttpHeaders_prefixHeader() throws IOException {
+ String projectId = "my-project";
+ String databaseId = "my-db";
+ MessageLite request =
+ RollbackRequest.newBuilder()
+ .setTransaction(ByteString.copyFromUtf8(projectId))
+ .setDatabaseId(databaseId)
+ .build();
+ RemoteRpc rpc =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest =
+ rpc.getClient().buildPostRequest(rpc.resolveURL("blah"), new ProtoHttpContent(request));
+ rpc.setHeaders(request, httpRequest, projectId, databaseId);
+ assertEquals(
+ "project_id=my-project&database_id=my-db",
+ httpRequest.getHeaders().get(RemoteRpc.X_GOOG_REQUEST_PARAMS_HEADER));
+
+ MessageLite request2 =
+ RollbackRequest.newBuilder().setTransaction(ByteString.copyFromUtf8(projectId)).build();
+ RemoteRpc rpc2 =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest2 =
+ rpc2.getClient().buildPostRequest(rpc2.resolveURL("blah"), new ProtoHttpContent(request2));
+ rpc2.setHeaders(request, httpRequest2, projectId, "");
+ assertEquals(
+ "project_id=my-project",
+ httpRequest2.getHeaders().get(RemoteRpc.X_GOOG_REQUEST_PARAMS_HEADER));
+ }
+
+ private static BeginTransactionResponse newBeginTransactionResponse() {
+ return BeginTransactionResponse.newBuilder()
+ .setTransaction(ByteString.copyFromUtf8("blah-blah-blah"))
+ .build();
+ }
+
+ private static RemoteRpc newRemoteRpc(InjectedTestValues injectedTestValues) {
+ return new RemoteRpc(
+ new MyHttpTransport(injectedTestValues).createRequestFactory(),
+ null,
+ "https://www.example.com/v1/projects/p");
+ }
+
+ private byte[] gzip(BeginTransactionResponse response) throws IOException {
+ ByteArrayOutputStream bytesOut = new ByteArrayOutputStream();
+ try (GZIPOutputStream gzipOut = new GZIPOutputStream(bytesOut)) {
+ response.writeTo(gzipOut);
+ }
+ return bytesOut.toByteArray();
+ }
+
+ private static class InjectedTestValues {
+ private final InputStream inputStream;
+ private final int contentLength;
+ private final boolean isGzip;
+
+ public InjectedTestValues(byte[] messageBytes, byte[] additionalBytes, boolean isGzip) {
+ byte[] allBytes = concat(messageBytes, additionalBytes);
+ this.inputStream = new ByteArrayInputStream(allBytes);
+ this.contentLength = allBytes.length;
+ this.isGzip = isGzip;
+ }
+
+ private static byte[] concat(byte[] a, byte[] b) {
+ byte[] c = new byte[a.length + b.length];
+ System.arraycopy(a, 0, c, 0, a.length);
+ System.arraycopy(b, 0, c, a.length, b.length);
+ return c;
+ }
+ }
+
+ /** {@link HttpTransport} that allows injection of the returned {@link LowLevelHttpRequest}. */
+ private static class MyHttpTransport extends HttpTransport {
+
+ private final InjectedTestValues injectedTestValues;
+
+ public MyHttpTransport(InjectedTestValues injectedTestValues) {
+ this.injectedTestValues = injectedTestValues;
+ }
+
+ @Override
+ protected LowLevelHttpRequest buildRequest(String method, String url) throws IOException {
+ return new MyLowLevelHttpRequest(injectedTestValues);
+ }
+ }
+
+ /**
+ * {@link LowLevelHttpRequest} that allows injection of the returned {@link LowLevelHttpResponse}.
+ */
+ private static class MyLowLevelHttpRequest extends LowLevelHttpRequest {
+
+ private final InjectedTestValues injectedTestValues;
+
+ public MyLowLevelHttpRequest(InjectedTestValues injectedTestValues) {
+ this.injectedTestValues = injectedTestValues;
+ }
+
+ @Override
+ public void addHeader(String name, String value) throws IOException {
+ // Do nothing.
+ }
+
+ @Override
+ public LowLevelHttpResponse execute() throws IOException {
+ return new MyLowLevelHttpResponse(injectedTestValues);
+ }
+ }
+
+ /** {@link LowLevelHttpResponse} that allows injected properties. */
+ private static class MyLowLevelHttpResponse extends LowLevelHttpResponse {
+
+ private final InjectedTestValues injectedTestValues;
+
+ public MyLowLevelHttpResponse(InjectedTestValues injectedTestValues) {
+ this.injectedTestValues = injectedTestValues;
+ }
+
+ @Override
+ public InputStream getContent() throws IOException {
+ return injectedTestValues.inputStream;
+ }
+
+ @Override
+ public String getContentEncoding() throws IOException {
+ return injectedTestValues.isGzip ? "gzip" : "";
+ }
+
+ @Override
+ public long getContentLength() throws IOException {
+ return injectedTestValues.contentLength;
+ }
+
+ @Override
+ public String getContentType() throws IOException {
+ return "application/x-protobuf";
+ }
+
+ @Override
+ public String getStatusLine() throws IOException {
+ return null;
+ }
+
+ @Override
+ public int getStatusCode() throws IOException {
+ return 200;
+ }
+
+ @Override
+ public String getReasonPhrase() throws IOException {
+ return null;
+ }
+
+ @Override
+ public int getHeaderCount() throws IOException {
+ return 0;
+ }
+
+ @Override
+ public String getHeaderName(int index) throws IOException {
+ return null;
+ }
+
+ @Override
+ public String getHeaderValue(int index) throws IOException {
+ return null;
+ }
+ }
+}
diff --git a/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/it/ITDatastoreProtoClientTest.java b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/it/ITDatastoreProtoClientTest.java
new file mode 100644
index 000000000000..c6df61ce762d
--- /dev/null
+++ b/java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/it/ITDatastoreProtoClientTest.java
@@ -0,0 +1,94 @@
+/*
+ * Copyright 2026 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.datastore.v1.client.it;
+
+import static com.google.datastore.v1.client.DatastoreHelper.makeFilter;
+import static com.google.datastore.v1.client.DatastoreHelper.makeValue;
+
+import com.google.common.truth.Truth;
+import com.google.datastore.v1.Filter;
+import com.google.datastore.v1.KindExpression;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.PropertyFilter;
+import com.google.datastore.v1.Query;
+import com.google.datastore.v1.client.Datastore;
+import com.google.datastore.v1.client.DatastoreException;
+import com.google.datastore.v1.client.DatastoreHelper;
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+import java.util.List;
+import org.junit.Before;
+import org.junit.Test;
+
+public class ITDatastoreProtoClientTest {
+
+ private static Datastore DATASTORE;
+
+ private static PartitionId PARTITION;
+
+ private static final String KIND = "test-kind";
+ private static final String PROJECT_ID = System.getenv(DatastoreHelper.PROJECT_ID_ENV_VAR);
+
+ @Before
+ public void setUp() throws GeneralSecurityException, IOException {
+ DATASTORE = DatastoreHelper.getDatastoreFromEnv();
+ }
+
+ @Test
+ public void testQuerySplitterWithDefaultDb() throws DatastoreException {
+ Filter propertyFilter =
+ makeFilter("foo", PropertyFilter.Operator.EQUAL, makeValue("value")).build();
+ Query query =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .setFilter(propertyFilter)
+ .build();
+
+ PARTITION = PartitionId.newBuilder().setProjectId(PROJECT_ID).build();
+
+ List splits =
+ DatastoreHelper.getQuerySplitter().getSplits(query, PARTITION, 2, DATASTORE);
+ Truth.assertThat(splits).isNotEmpty();
+ splits.forEach(
+ split -> {
+ Truth.assertThat(split.getKind(0).getName()).isEqualTo(KIND);
+ Truth.assertThat(split.getFilter()).isEqualTo(propertyFilter);
+ });
+ }
+
+ @Test
+ public void testQuerySplitterWithDb() throws DatastoreException {
+ Filter propertyFilter =
+ makeFilter("foo", PropertyFilter.Operator.EQUAL, makeValue("value")).build();
+ Query query =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .setFilter(propertyFilter)
+ .build();
+
+ PARTITION = PartitionId.newBuilder().setProjectId(PROJECT_ID).setDatabaseId("test-db").build();
+
+ List splits =
+ DatastoreHelper.getQuerySplitter().getSplits(query, PARTITION, 2, DATASTORE);
+
+ Truth.assertThat(splits).isNotEmpty();
+ splits.forEach(
+ split -> {
+ Truth.assertThat(split.getKind(0).getName()).isEqualTo(KIND);
+ Truth.assertThat(split.getFilter()).isEqualTo(propertyFilter);
+ });
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-bom/pom.xml b/java-datastore/google-cloud-datastore-bom/pom.xml
new file mode 100644
index 000000000000..be45f940c304
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-bom/pom.xml
@@ -0,0 +1,87 @@
+
+
+ 4.0.0
+ com.google.cloud
+ google-cloud-datastore-bom
+ 2.33.2
+ pom
+
+ com.google.cloud
+ google-cloud-pom-parent
+ 1.77.0-SNAPSHOT
+ ../../google-cloud-pom-parent/pom.xml
+
+
+ Google Cloud datastore BOM
+ https://github.com/googleapis/google-cloud-java
+
+ BOM for Google Cloud datastore
+
+
+
+ Google LLC
+
+
+
+
+ chingor13
+ Jeff Ching
+ chingor@google.com
+ Google LLC
+
+ Developer
+
+
+
+
+
+ scm:git:https://github.com/googleapis/google-cloud-java.git
+ scm:git:git@github.com:googleapis/google-cloud-java.git
+ https://github.com/googleapis/google-cloud-java
+
+
+
+
+ The Apache Software License, Version 2.0
+ http://www.apache.org/licenses/LICENSE-2.0.txt
+ repo
+
+
+
+
+
+
+ com.google.cloud
+ google-cloud-datastore
+ 2.33.2
+
+
+ com.google.api.grpc
+ grpc-google-cloud-datastore-admin-v1
+ 2.33.2
+
+
+ com.google.api.grpc
+ proto-google-cloud-datastore-v1
+ 0.124.2
+
+
+ com.google.api.grpc
+ proto-google-cloud-datastore-admin-v1
+ 2.33.2
+
+
+
+
+
+
+
+ org.apache.maven.plugins
+ maven-checkstyle-plugin
+
+ true
+
+
+
+
+
diff --git a/java-datastore/google-cloud-datastore-utils/pom.xml b/java-datastore/google-cloud-datastore-utils/pom.xml
new file mode 100644
index 000000000000..3d5e26875790
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/pom.xml
@@ -0,0 +1,153 @@
+
+
+ 4.0.0
+ com.google.cloud
+ google-cloud-datastore-utils
+ 2.33.2
+ jar
+ Google Cloud Datastore Utilities
+ https://github.com/googleapis/java-datastore
+
+ Java datastore client utility library.
+
+
+ com.google.cloud
+ google-cloud-datastore-parent
+ 2.33.2
+
+
+ google-cloud-datastore-utils
+
+
+
+ com.google.api-client
+ google-api-client
+
+
+ com.google.http-client
+ google-http-client-protobuf
+
+
+ com.google.http-client
+ google-http-client-gson
+
+
+ com.google.api.grpc
+ proto-google-cloud-datastore-v1
+
+
+ com.google.api
+ api-common
+
+
+ com.google.protobuf
+ protobuf-java
+
+
+ com.google.guava
+ guava
+
+
+ com.google.api.grpc
+ proto-google-common-protos
+
+
+ com.google.http-client
+ google-http-client
+
+
+ com.google.http-client
+ google-http-client-jackson2
+
+
+ com.google.oauth-client
+ google-oauth-client
+
+
+ com.google.code.findbugs
+ jsr305
+
+
+
+ junit
+ junit
+ test
+
+
+ com.google.truth
+ truth
+ 1.4.2
+ test
+
+
+ org.checkerframework
+ checker-qual
+
+
+
+
+
+
+
+
+ org.apache.maven.plugins
+ maven-surefire-plugin
+
+ -Xmx2048m
+
+
+
+
+
+
+
+ native
+
+
+ true
+
+
+
+ java17
+
+ [17,)
+
+
+
+
+ org.apache.maven.plugins
+ maven-compiler-plugin
+
+ UTF-8
+ true
+
+ -XDcompilePolicy=simple
+ --should-stop=ifError=FLOW
+ -Xplugin:ErrorProne -XepExcludedPaths:.*/generated-sources/.*
+
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
+ -J--add-opens=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
+ -J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED
+
+
+
+
+ com.google.errorprone
+ error_prone_core
+ ${error-prone.version}
+
+
+
+
+
+
+
+
+
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/Datastore.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/Datastore.java
new file mode 100644
index 000000000000..92e2e0a6d00f
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/Datastore.java
@@ -0,0 +1,136 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import com.google.datastore.v1.*;
+import com.google.rpc.Code;
+import java.io.IOException;
+import java.io.InputStream;
+
+/**
+ * Provides access to Cloud Datastore.
+ *
+ * This class is thread-safe.
+ */
+public class Datastore {
+
+ final RemoteRpc remoteRpc;
+
+ Datastore(RemoteRpc remoteRpc) {
+ this.remoteRpc = remoteRpc;
+ }
+
+ /** Reset the RPC count. */
+ public void resetRpcCount() {
+ remoteRpc.resetRpcCount();
+ }
+
+ /**
+ * Returns the number of RPC calls made since the client was created or {@link #resetRpcCount} was
+ * called.
+ */
+ public int getRpcCount() {
+ return remoteRpc.getRpcCount();
+ }
+
+ private com.google.datastore.utils.DatastoreException invalidResponseException(
+ String method, IOException exception) {
+ return RemoteRpc.makeException(
+ remoteRpc.getUrl(), method, Code.UNAVAILABLE, "Invalid response", exception);
+ }
+
+ public AllocateIdsResponse allocateIds(AllocateIdsRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call("allocateIds", request, request.getProjectId(), request.getDatabaseId())) {
+ return AllocateIdsResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("allocateIds", exception);
+ }
+ }
+
+ public BeginTransactionResponse beginTransaction(BeginTransactionRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call(
+ "beginTransaction", request, request.getProjectId(), request.getDatabaseId())) {
+ return BeginTransactionResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("beginTransaction", exception);
+ }
+ }
+
+ public CommitResponse commit(CommitRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call("commit", request, request.getProjectId(), request.getDatabaseId())) {
+ return CommitResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("commit", exception);
+ }
+ }
+
+ public LookupResponse lookup(LookupRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call("lookup", request, request.getProjectId(), request.getDatabaseId())) {
+ return LookupResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("lookup", exception);
+ }
+ }
+
+ public ReserveIdsResponse reserveIds(ReserveIdsRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call("reserveIds", request, request.getProjectId(), request.getDatabaseId())) {
+ return ReserveIdsResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("reserveIds", exception);
+ }
+ }
+
+ public RollbackResponse rollback(RollbackRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call("rollback", request, request.getProjectId(), request.getDatabaseId())) {
+ return RollbackResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("rollback", exception);
+ }
+ }
+
+ public RunQueryResponse runQuery(RunQueryRequest request)
+ throws com.google.datastore.utils.DatastoreException {
+ try (InputStream is =
+ remoteRpc.call("runQuery", request, request.getProjectId(), request.getDatabaseId())) {
+ return RunQueryResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("runQuery", exception);
+ }
+ }
+
+ public RunAggregationQueryResponse runAggregationQuery(RunAggregationQueryRequest request)
+ throws DatastoreException {
+ try (InputStream is =
+ remoteRpc.call(
+ "runAggregationQuery", request, request.getProjectId(), request.getDatabaseId())) {
+ return RunAggregationQueryResponse.parseFrom(is);
+ } catch (IOException exception) {
+ throw invalidResponseException("runAggregationQuery", exception);
+ }
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreException.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreException.java
new file mode 100644
index 000000000000..20913b5e12e5
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreException.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import com.google.rpc.Code;
+
+/** Indicates an error in a {@link Datastore} call. */
+public class DatastoreException extends Exception {
+ private final String methodName;
+ private final Code code;
+
+ public DatastoreException(String methodName, Code code, String message, Throwable cause) {
+ super(message, cause);
+ this.methodName = methodName;
+ this.code = code;
+ }
+
+ /**
+ * @return the canonical error code
+ */
+ public Code getCode() {
+ return code;
+ }
+
+ /**
+ * @return the datastore method name
+ */
+ public String getMethodName() {
+ return methodName;
+ }
+
+ @Override
+ public String toString() {
+ return String.format("%s, code=%s", super.toString(), code);
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreFactory.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreFactory.java
new file mode 100644
index 000000000000..cdd1698d5c28
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreFactory.java
@@ -0,0 +1,127 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.HttpRequestFactory;
+import com.google.api.client.http.HttpTransport;
+import com.google.api.client.http.javanet.NetHttpTransport;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.util.Arrays;
+import java.util.logging.*;
+
+/** Client factory for {@link com.google.datastore.utils.Datastore}. */
+public class DatastoreFactory {
+
+ // Lazy load this because we might be running inside App Engine and this
+ // class isn't on the whitelist.
+ private static ConsoleHandler methodHandler;
+
+ /** API version. */
+ public static final String VERSION = "v1";
+
+ public static final String DEFAULT_HOST = "https://datastore.googleapis.com";
+
+ /** Singleton factory instance. */
+ private static final DatastoreFactory INSTANCE = new DatastoreFactory();
+
+ public static DatastoreFactory get() {
+ return INSTANCE;
+ }
+
+ /**
+ * Provides access to a datastore using the provided options. Logs into the application using the
+ * credentials available via these options.
+ *
+ * @throws IllegalArgumentException if the server or credentials weren't provided.
+ */
+ public com.google.datastore.utils.Datastore create(
+ com.google.datastore.utils.DatastoreOptions options) {
+ return new com.google.datastore.utils.Datastore(newRemoteRpc(options));
+ }
+
+ /** Constructs a Google APIs HTTP client with the associated credentials. */
+ public HttpRequestFactory makeClient(com.google.datastore.utils.DatastoreOptions options) {
+ Credential credential = options.getCredential();
+ HttpTransport transport = options.getTransport();
+ if (transport == null) {
+ transport = credential == null ? new NetHttpTransport() : credential.getTransport();
+ transport = transport == null ? new NetHttpTransport() : transport;
+ }
+ return transport.createRequestFactory(credential);
+ }
+
+ /** Starts logging datastore method calls to the console. (Useful within tests.) */
+ public static void logMethodCalls() {
+ Logger logger = Logger.getLogger(Datastore.class.getName());
+ logger.setLevel(Level.FINE);
+ if (!Arrays.asList(logger.getHandlers()).contains(getStreamHandler())) {
+ logger.addHandler(getStreamHandler());
+ }
+ }
+
+ /** Build a valid datastore URL. */
+ String buildProjectEndpoint(com.google.datastore.utils.DatastoreOptions options) {
+ if (options.getProjectEndpoint() != null) {
+ return options.getProjectEndpoint();
+ }
+ // DatastoreOptions ensures either project endpoint or project ID is set.
+ String projectId = checkNotNull(options.getProjectId());
+ if (options.getHost() != null) {
+ return validateUrl(
+ String.format("https://%s/%s/projects/%s", options.getHost(), VERSION, projectId));
+ } else if (options.getLocalHost() != null) {
+ return validateUrl(
+ String.format("http://%s/%s/projects/%s", options.getLocalHost(), VERSION, projectId));
+ }
+ return validateUrl(String.format("%s/%s/projects/%s", DEFAULT_HOST, VERSION, projectId));
+ }
+
+ protected com.google.datastore.utils.RemoteRpc newRemoteRpc(DatastoreOptions options) {
+ checkNotNull(options);
+ HttpRequestFactory client = makeClient(options);
+ return new com.google.datastore.utils.RemoteRpc(
+ client, options.getInitializer(), buildProjectEndpoint(options));
+ }
+
+ private static String validateUrl(String url) {
+ try {
+ return new URI(url).toString();
+ } catch (URISyntaxException e) {
+ throw new IllegalArgumentException(e);
+ }
+ }
+
+ // TODO: Support something other than console handler for when we're
+ // running in App Engine
+ private static synchronized StreamHandler getStreamHandler() {
+ if (methodHandler == null) {
+ methodHandler = new ConsoleHandler();
+ methodHandler.setFormatter(
+ new Formatter() {
+ @Override
+ public String format(LogRecord record) {
+ return record.getMessage() + "\n";
+ }
+ });
+ methodHandler.setLevel(Level.FINE);
+ }
+ return methodHandler;
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreHelper.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreHelper.java
new file mode 100644
index 000000000000..0001cfb09dff
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreHelper.java
@@ -0,0 +1,731 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
+import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
+import com.google.api.client.http.GenericUrl;
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpTransport;
+import com.google.api.client.json.JsonFactory;
+import com.google.api.client.json.gson.GsonFactory;
+import com.google.datastore.v1.ArrayValue;
+import com.google.datastore.v1.CompositeFilter;
+import com.google.datastore.v1.Entity;
+import com.google.datastore.v1.Filter;
+import com.google.datastore.v1.Key;
+import com.google.datastore.v1.Key.PathElement;
+import com.google.datastore.v1.Key.PathElement.IdTypeCase;
+import com.google.datastore.v1.Mutation;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.PropertyFilter;
+import com.google.datastore.v1.PropertyOrder;
+import com.google.datastore.v1.PropertyReference;
+import com.google.datastore.v1.Value;
+import com.google.datastore.v1.Value.ValueTypeCase;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.Timestamp;
+import com.google.protobuf.TimestampOrBuilder;
+import com.google.type.LatLng;
+import java.io.File;
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+import java.security.PrivateKey;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import javax.annotation.Nullable;
+
+/** Helper methods for {@link Datastore}. */
+// TODO: Accept OrBuilders when possible.
+public final class DatastoreHelper {
+ private static final Logger logger =
+ Logger.getLogger(com.google.datastore.utils.DatastoreHelper.class.getName());
+
+ private static final int MICROSECONDS_PER_SECOND = 1000 * 1000;
+ private static final int NANOSECONDS_PER_MICROSECOND = 1000;
+
+ /** The property used in the Datastore to give us a random distribution. * */
+ public static final String SCATTER_PROPERTY_NAME = "__scatter__";
+
+ /** The property used in the Datastore to get the key of the entity. * */
+ public static final String KEY_PROPERTY_NAME = "__key__";
+
+ /** Name of the environment variable used to set the project ID. */
+ public static final String PROJECT_ID_ENV_VAR = "DATASTORE_PROJECT_ID";
+
+ /** Name of the environment variable used to set the local host. */
+ public static final String LOCAL_HOST_ENV_VAR = "DATASTORE_EMULATOR_HOST";
+
+ /** Name of the environment variable used to set the service account. */
+ public static final String SERVICE_ACCOUNT_ENV_VAR = "DATASTORE_SERVICE_ACCOUNT";
+
+ /** Name of the environment variable used to set the private key file. */
+ public static final String PRIVATE_KEY_FILE_ENV_VAR = "DATASTORE_PRIVATE_KEY_FILE";
+
+ private static final String URL_OVERRIDE_ENV_VAR = "__DATASTORE_URL_OVERRIDE";
+
+ private static final AtomicReference projectIdFromComputeEngine = new AtomicReference<>();
+
+ /** Comparator for Keys */
+ private static final class KeyComparator implements Comparator {
+
+ static final com.google.datastore.utils.DatastoreHelper.KeyComparator INSTANCE =
+ new com.google.datastore.utils.DatastoreHelper.KeyComparator();
+
+ private int comparePathElement(PathElement thisElement, PathElement otherElement) {
+ int result = thisElement.getKind().compareTo(otherElement.getKind());
+ if (result != 0) {
+ return result;
+ }
+ if (thisElement.getIdTypeCase() == IdTypeCase.ID) {
+ if (otherElement.getIdTypeCase() != IdTypeCase.ID) {
+ return -1;
+ }
+ return Long.valueOf(thisElement.getId()).compareTo(otherElement.getId());
+ }
+ if (otherElement.getIdTypeCase() == IdTypeCase.ID) {
+ return 1;
+ }
+
+ return thisElement.getName().compareTo(otherElement.getName());
+ }
+
+ @Override
+ public int compare(Key thisKey, Key otherKey) {
+ if (!thisKey.getPartitionId().equals(otherKey.getPartitionId())) {
+ throw new IllegalArgumentException("Cannot compare keys with different partition ids.");
+ }
+
+ Iterator thisPath = thisKey.getPathList().iterator();
+ Iterator otherPath = otherKey.getPathList().iterator();
+ while (thisPath.hasNext()) {
+ if (!otherPath.hasNext()) {
+ return 1;
+ }
+ int result = comparePathElement(thisPath.next(), otherPath.next());
+ if (result != 0) {
+ return result;
+ }
+ }
+
+ return otherPath.hasNext() ? -1 : 0;
+ }
+ }
+
+ private DatastoreHelper() {}
+
+ private static HttpTransport newTransport() throws GeneralSecurityException, IOException {
+ return GoogleNetHttpTransport.newTrustedTransport();
+ }
+
+ static JsonFactory newJsonFactory() {
+ return new GsonFactory();
+ }
+
+ /**
+ * Constructs credentials for the given account and key.
+ *
+ * @param serviceAccountId service account ID (typically an e-mail address).
+ * @param privateKeyFile the file name from which to get the private key.
+ * @return valid credentials or {@code null}
+ */
+ public static Credential getServiceAccountCredential(
+ String serviceAccountId, String privateKeyFile) throws GeneralSecurityException, IOException {
+ return getServiceAccountCredential(serviceAccountId, privateKeyFile, DatastoreOptions.SCOPES);
+ }
+
+ /**
+ * Constructs credentials for the given account and key file.
+ *
+ * @param serviceAccountId service account ID (typically an e-mail address).
+ * @param privateKeyFile the file name from which to get the private key.
+ * @param serviceAccountScopes Collection of OAuth scopes to use with the the service account flow
+ * or {@code null} if not.
+ * @return valid credentials or {@code null}
+ */
+ public static Credential getServiceAccountCredential(
+ String serviceAccountId, String privateKeyFile, Collection serviceAccountScopes)
+ throws GeneralSecurityException, IOException {
+ return getCredentialBuilderWithoutPrivateKey(serviceAccountId, serviceAccountScopes)
+ .setServiceAccountPrivateKeyFromP12File(new File(privateKeyFile))
+ .build();
+ }
+
+ /**
+ * Constructs credentials for the given account and key.
+ *
+ * @param serviceAccountId service account ID (typically an e-mail address).
+ * @param privateKey the private key for the given account.
+ * @param serviceAccountScopes Collection of OAuth scopes to use with the the service account flow
+ * or {@code null} if not.
+ * @return valid credentials or {@code null}
+ */
+ public static Credential getServiceAccountCredential(
+ String serviceAccountId, PrivateKey privateKey, Collection serviceAccountScopes)
+ throws GeneralSecurityException, IOException {
+ return getCredentialBuilderWithoutPrivateKey(serviceAccountId, serviceAccountScopes)
+ .setServiceAccountPrivateKey(privateKey)
+ .build();
+ }
+
+ private static GoogleCredential.Builder getCredentialBuilderWithoutPrivateKey(
+ String serviceAccountId, Collection serviceAccountScopes)
+ throws GeneralSecurityException, IOException {
+ HttpTransport transport = newTransport();
+ JsonFactory jsonFactory = newJsonFactory();
+ return new GoogleCredential.Builder()
+ .setTransport(transport)
+ .setJsonFactory(jsonFactory)
+ .setServiceAccountId(serviceAccountId)
+ .setServiceAccountScopes(serviceAccountScopes);
+ }
+
+ /**
+ * Constructs a {@link Datastore} from environment variables and/or the Compute Engine metadata
+ * server.
+ *
+ * The project ID is determined from, in order of preference:
+ *
+ *
+ * - DATASTORE_PROJECT_ID environment variable
+ *
- Compute Engine
+ *
+ *
+ * Credentials are taken from, in order of preference:
+ *
+ *
+ * - No credentials (if the DATASTORE_EMULATOR_HOST environment variable is set)
+ *
- Service Account specified by the DATASTORE_SERVICE_ACCOUNT and DATASTORE_PRIVATE_KEY_FILE
+ * environment variables
+ *
- Google Application Default as described here.
+ *
+ */
+ public static DatastoreOptions.Builder getOptionsFromEnv()
+ throws GeneralSecurityException, IOException {
+ DatastoreOptions.Builder options = new DatastoreOptions.Builder();
+ setProjectEndpointFromEnv(options);
+ options.credential(getCredentialFromEnv());
+ return options;
+ }
+
+ private static Credential getCredentialFromEnv() throws GeneralSecurityException, IOException {
+ if (System.getenv(LOCAL_HOST_ENV_VAR) != null) {
+ logger.log(
+ Level.INFO,
+ "{0} environment variable was set. Not using credentials.",
+ new Object[] {LOCAL_HOST_ENV_VAR});
+ return null;
+ }
+ String serviceAccount = System.getenv(SERVICE_ACCOUNT_ENV_VAR);
+ String privateKeyFile = System.getenv(PRIVATE_KEY_FILE_ENV_VAR);
+ if (serviceAccount != null && privateKeyFile != null) {
+ logger.log(
+ Level.INFO,
+ "{0} and {1} environment variables were set. " + "Using service account credential.",
+ new Object[] {SERVICE_ACCOUNT_ENV_VAR, PRIVATE_KEY_FILE_ENV_VAR});
+ return getServiceAccountCredential(serviceAccount, privateKeyFile);
+ }
+ return GoogleCredential.getApplicationDefault().createScoped(DatastoreOptions.SCOPES);
+ }
+
+ /**
+ * Determines the project id from the environment. Uses the following sources in order of
+ * preference:
+ *
+ *
+ * - Value of the DATASTORE_PROJECT_ID environment variable
+ *
- Compute Engine
+ *
+ *
+ * @throws IllegalStateException if the project ID cannot be determined
+ */
+ private static String getProjectIdFromEnv() {
+ if (System.getenv(PROJECT_ID_ENV_VAR) != null) {
+ return System.getenv(PROJECT_ID_ENV_VAR);
+ }
+ String projectIdFromComputeEngine = getProjectIdFromComputeEngine();
+ if (projectIdFromComputeEngine != null) {
+ return projectIdFromComputeEngine;
+ }
+ throw new IllegalStateException(
+ String.format(
+ "Could not determine project ID."
+ + " If you are not running on Compute Engine, set the"
+ + " %s environment variable.",
+ PROJECT_ID_ENV_VAR));
+ }
+
+ /**
+ * Gets the project ID from the Compute Engine metadata server. Returns {@code null} if the
+ * project ID cannot be determined (because, for instance, the code is not running on Compute
+ * Engine).
+ */
+ @Nullable
+ public static String getProjectIdFromComputeEngine() {
+ String cachedProjectId = projectIdFromComputeEngine.get();
+ return cachedProjectId != null ? cachedProjectId : queryProjectIdFromComputeEngine();
+ }
+
+ @Nullable
+ private static String queryProjectIdFromComputeEngine() {
+ HttpTransport transport;
+
+ try {
+ transport = newTransport();
+ } catch (GeneralSecurityException | IOException e) {
+ logger.log(Level.WARNING, "Failed to create HttpTransport.", e);
+ return null;
+ }
+
+ try {
+ GenericUrl projectIdUrl =
+ new GenericUrl("http://metadata/computeMetadata/v1/project/project-id");
+ HttpRequest request = transport.createRequestFactory().buildGetRequest(projectIdUrl);
+ request.getHeaders().set("Metadata-Flavor", "Google");
+ String result = request.execute().parseAsString();
+ projectIdFromComputeEngine.set(result);
+ return result;
+ } catch (IOException e) {
+ logger.log(Level.INFO, "Could not determine project ID from Compute Engine.", e);
+ return null;
+ }
+ }
+
+ private static void setProjectEndpointFromEnv(DatastoreOptions.Builder options) {
+ // DATASTORE_HOST is deprecated.
+ if (System.getenv("DATASTORE_HOST") != null) {
+ logger.warning(
+ String.format(
+ "Ignoring value of environment variable DATASTORE_HOST. "
+ + "To point datastore to a host running locally, use "
+ + "the environment variable %s.",
+ LOCAL_HOST_ENV_VAR));
+ }
+ String projectId = getProjectIdFromEnv();
+ if (System.getenv(URL_OVERRIDE_ENV_VAR) != null) {
+ options.projectEndpoint(
+ String.format("%s/projects/%s", System.getenv(URL_OVERRIDE_ENV_VAR), projectId));
+ return;
+ }
+ if (System.getenv(LOCAL_HOST_ENV_VAR) != null) {
+ options.projectId(projectId);
+ options.localHost(System.getenv(LOCAL_HOST_ENV_VAR));
+ return;
+ }
+ options.projectId(projectId);
+ return;
+ }
+
+ /**
+ * @see #getOptionsFromEnv()
+ */
+ public static Datastore getDatastoreFromEnv() throws GeneralSecurityException, IOException {
+ return DatastoreFactory.get().create(getOptionsFromEnv().build());
+ }
+
+ /**
+ * Gets a {@link com.google.datastore.utils.QuerySplitter}.
+ *
+ * The returned {@link com.google.datastore.utils.QuerySplitter#getSplits} cannot accept a
+ * query that contains inequality filters, a sort filter, or a missing kind.
+ */
+ public static QuerySplitter getQuerySplitter() {
+ return com.google.datastore.utils.QuerySplitterImpl.INSTANCE;
+ }
+
+ public static Comparator getKeyComparator() {
+ return com.google.datastore.utils.DatastoreHelper.KeyComparator.INSTANCE;
+ }
+
+ /** Make a sort order for use in a query. */
+ public static PropertyOrder.Builder makeOrder(
+ String property, PropertyOrder.Direction direction) {
+ return PropertyOrder.newBuilder()
+ .setProperty(makePropertyReference(property))
+ .setDirection(direction);
+ }
+
+ /** Makes an ancestor filter. */
+ public static Filter.Builder makeAncestorFilter(Key ancestor) {
+ return makeFilter(
+ com.google.datastore.utils.DatastoreHelper.KEY_PROPERTY_NAME,
+ PropertyFilter.Operator.HAS_ANCESTOR,
+ makeValue(ancestor));
+ }
+
+ /** Make a filter on a property for use in a query. */
+ public static Filter.Builder makeFilter(
+ String property, PropertyFilter.Operator operator, Value value) {
+ return Filter.newBuilder()
+ .setPropertyFilter(
+ PropertyFilter.newBuilder()
+ .setProperty(makePropertyReference(property))
+ .setOp(operator)
+ .setValue(value));
+ }
+
+ /** Make a filter on a property for use in a query. */
+ public static Filter.Builder makeFilter(
+ String property, PropertyFilter.Operator operator, Value.Builder value) {
+ return makeFilter(property, operator, value.build());
+ }
+
+ /** Make a composite filter from the given sub-filters using AND to combine filters. */
+ public static Filter.Builder makeAndFilter(Filter... subfilters) {
+ return makeAndFilter(Arrays.asList(subfilters));
+ }
+
+ /** Make a composite filter from the given sub-filters using AND to combine filters. */
+ public static Filter.Builder makeAndFilter(Iterable subfilters) {
+ return Filter.newBuilder()
+ .setCompositeFilter(
+ CompositeFilter.newBuilder()
+ .addAllFilters(subfilters)
+ .setOp(CompositeFilter.Operator.AND));
+ }
+
+ /** Make a property reference for use in a query. */
+ public static PropertyReference.Builder makePropertyReference(String propertyName) {
+ return PropertyReference.newBuilder().setName(propertyName);
+ }
+
+ /** Make an array value containing the specified values. */
+ public static Value.Builder makeValue(Iterable values) {
+ return Value.newBuilder().setArrayValue(ArrayValue.newBuilder().addAllValues(values));
+ }
+
+ /** Make a list value containing the specified values. */
+ public static Value.Builder makeValue(Value value1, Value value2, Value... rest) {
+ ArrayValue.Builder arrayValue = ArrayValue.newBuilder();
+ arrayValue.addValues(value1);
+ arrayValue.addValues(value2);
+ arrayValue.addAllValues(Arrays.asList(rest));
+ return Value.newBuilder().setArrayValue(arrayValue);
+ }
+
+ /** Make an array value containing the specified values. */
+ public static Value.Builder makeValue(
+ Value.Builder value1, Value.Builder value2, Value.Builder... rest) {
+ ArrayValue.Builder arrayValue = ArrayValue.newBuilder();
+ arrayValue.addValues(value1);
+ arrayValue.addValues(value2);
+ for (Value.Builder builder : rest) {
+ arrayValue.addValues(builder);
+ }
+ return Value.newBuilder().setArrayValue(arrayValue);
+ }
+
+ /** Make a key value. */
+ public static Value.Builder makeValue(Key key) {
+ return Value.newBuilder().setKeyValue(key);
+ }
+
+ /** Make a key value. */
+ public static Value.Builder makeValue(Key.Builder key) {
+ return makeValue(key.build());
+ }
+
+ /** Make an integer value. */
+ public static Value.Builder makeValue(long key) {
+ return Value.newBuilder().setIntegerValue(key);
+ }
+
+ /** Make a floating point value. */
+ public static Value.Builder makeValue(double value) {
+ return Value.newBuilder().setDoubleValue(value);
+ }
+
+ /** Make a boolean value. */
+ public static Value.Builder makeValue(boolean value) {
+ return Value.newBuilder().setBooleanValue(value);
+ }
+
+ /** Make a string value. */
+ public static Value.Builder makeValue(String value) {
+ return Value.newBuilder().setStringValue(value);
+ }
+
+ /** Make an entity value. */
+ public static Value.Builder makeValue(Entity entity) {
+ return Value.newBuilder().setEntityValue(entity);
+ }
+
+ /** Make a entity value. */
+ public static Value.Builder makeValue(Entity.Builder entity) {
+ return makeValue(entity.build());
+ }
+
+ /** Make a ByteString value. */
+ public static Value.Builder makeValue(ByteString blob) {
+ return Value.newBuilder().setBlobValue(blob);
+ }
+
+ /** Make a timestamp value given a date. */
+ public static Value.Builder makeValue(Date date) {
+ return Value.newBuilder().setTimestampValue(toTimestamp(date.getTime() * 1000L));
+ }
+
+ /** Makes a GeoPoint value. */
+ public static Value.Builder makeValue(LatLng value) {
+ return Value.newBuilder().setGeoPointValue(value);
+ }
+
+ /** Makes a GeoPoint value. */
+ public static Value.Builder makeValue(LatLng.Builder value) {
+ return makeValue(value.build());
+ }
+
+ private static Timestamp.Builder toTimestamp(long microseconds) {
+ long seconds = microseconds / MICROSECONDS_PER_SECOND;
+ long microsecondsRemainder = microseconds % MICROSECONDS_PER_SECOND;
+ if (microsecondsRemainder < 0) {
+ // Nanos must be positive even if microseconds is negative.
+ // Java modulus doesn't take care of this for us.
+ microsecondsRemainder += MICROSECONDS_PER_SECOND;
+ seconds -= 1;
+ }
+ return Timestamp.newBuilder()
+ .setSeconds(seconds)
+ .setNanos((int) microsecondsRemainder * NANOSECONDS_PER_MICROSECOND);
+ }
+
+ /**
+ * Make a key from the specified path of kind/id-or-name pairs and/or Keys.
+ *
+ * The id-or-name values must be either String, Long, Integer or Short.
+ *
+ *
The last id-or-name value may be omitted, in which case an entity without an id is created
+ * (for use with automatic id allocation).
+ *
+ *
The PartitionIds of all Keys in the path must be equal. The returned Key.Builder will use
+ * this PartitionId.
+ */
+ public static Key.Builder makeKey(Object... elements) {
+ Key.Builder key = Key.newBuilder();
+ PartitionId partitionId = null;
+ for (int pathIndex = 0; pathIndex < elements.length; pathIndex += 2) {
+ PathElement.Builder pathElement = PathElement.newBuilder();
+ Object element = elements[pathIndex];
+ if (element instanceof Key) {
+ Key subKey = (Key) element;
+ if (partitionId == null) {
+ partitionId = subKey.getPartitionId();
+ } else if (!partitionId.equals(subKey.getPartitionId())) {
+ throw new IllegalArgumentException(
+ "Partition IDs did not match, found: "
+ + partitionId
+ + " and "
+ + subKey.getPartitionId());
+ }
+ key.addAllPath(((Key) element).getPathList());
+ // We increment by 2, but since we got a Key argument we're only consuming 1 element in this
+ // iteration of the loop. Decrement the index so that when we jump by 2 we end up in the
+ // right spot.
+ pathIndex--;
+ } else {
+ String kind;
+ try {
+ kind = (String) element;
+ } catch (ClassCastException e) {
+ throw new IllegalArgumentException(
+ "Expected string or Key, got: " + element.getClass(), e);
+ }
+ pathElement.setKind(kind);
+ if (pathIndex + 1 < elements.length) {
+ Object value = elements[pathIndex + 1];
+ if (value instanceof String) {
+ pathElement.setName((String) value);
+ } else if (value instanceof Long) {
+ pathElement.setId((Long) value);
+ } else if (value instanceof Integer) {
+ pathElement.setId((Integer) value);
+ } else if (value instanceof Short) {
+ pathElement.setId((Short) value);
+ } else {
+ throw new IllegalArgumentException(
+ "Expected string or integer, got: " + value.getClass());
+ }
+ }
+ key.addPath(pathElement);
+ }
+ }
+ if (partitionId != null && !partitionId.equals(PartitionId.getDefaultInstance())) {
+ key.setPartitionId(partitionId);
+ }
+ return key;
+ }
+
+ /**
+ * @return the double contained in value
+ * @throws IllegalArgumentException if the value does not contain a double.
+ */
+ public static double getDouble(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.DOUBLE_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a double.");
+ }
+ return value.getDoubleValue();
+ }
+
+ /**
+ * @return the key contained in value
+ * @throws IllegalArgumentException if the value does not contain a key.
+ */
+ public static Key getKey(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.KEY_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a key.");
+ }
+ return value.getKeyValue();
+ }
+
+ /**
+ * @return the blob contained in value
+ * @throws IllegalArgumentException if the value does not contain a blob.
+ */
+ public static ByteString getByteString(Value value) {
+ if (value.getMeaning() == 18 && value.getValueTypeCase() == ValueTypeCase.STRING_VALUE) {
+ return value.getStringValueBytes();
+ } else if (value.getValueTypeCase() == ValueTypeCase.BLOB_VALUE) {
+ return value.getBlobValue();
+ }
+ throw new IllegalArgumentException("Value does not contain a blob.");
+ }
+
+ /**
+ * @return the entity contained in value
+ * @throws IllegalArgumentException if the value does not contain an entity.
+ */
+ public static Entity getEntity(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.ENTITY_VALUE) {
+ throw new IllegalArgumentException("Value does not contain an Entity.");
+ }
+ return value.getEntityValue();
+ }
+
+ /**
+ * @return the string contained in value
+ * @throws IllegalArgumentException if the value does not contain a string.
+ */
+ public static String getString(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.STRING_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a string.");
+ }
+ return value.getStringValue();
+ }
+
+ /**
+ * @return the boolean contained in value
+ * @throws IllegalArgumentException if the value does not contain a boolean.
+ */
+ public static boolean getBoolean(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.BOOLEAN_VALUE) {
+ throw new IllegalArgumentException("Value does not contain a boolean.");
+ }
+ return value.getBooleanValue();
+ }
+
+ /**
+ * @return the long contained in value
+ * @throws IllegalArgumentException if the value does not contain a long.
+ */
+ public static long getLong(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.INTEGER_VALUE) {
+ throw new IllegalArgumentException("Value does not contain an integer.");
+ }
+ return value.getIntegerValue();
+ }
+
+ /**
+ * @return the timestamp in microseconds contained in value
+ * @throws IllegalArgumentException if the value does not contain a timestamp.
+ */
+ public static long getTimestamp(Value value) {
+ if (value.getMeaning() == 18 && value.getValueTypeCase() == ValueTypeCase.INTEGER_VALUE) {
+ return value.getIntegerValue();
+ } else if (value.getValueTypeCase() == ValueTypeCase.TIMESTAMP_VALUE) {
+ return toMicroseconds(value.getTimestampValue());
+ }
+ throw new IllegalArgumentException("Value does not contain a timestamp.");
+ }
+
+ private static long toMicroseconds(TimestampOrBuilder timestamp) {
+ // Nanosecond precision is lost.
+ return timestamp.getSeconds() * MICROSECONDS_PER_SECOND
+ + timestamp.getNanos() / NANOSECONDS_PER_MICROSECOND;
+ }
+
+ /**
+ * @return the array contained in value as a list.
+ * @throws IllegalArgumentException if the value does not contain an array.
+ */
+ public static List getList(Value value) {
+ if (value.getValueTypeCase() != ValueTypeCase.ARRAY_VALUE) {
+ throw new IllegalArgumentException("Value does not contain an array.");
+ }
+ return value.getArrayValue().getValuesList();
+ }
+
+ /**
+ * Convert a timestamp value into a {@link Date} clipping off the microseconds.
+ *
+ * @param value a timestamp value to convert
+ * @return the resulting {@link Date}
+ * @throws IllegalArgumentException if the value does not contain a timestamp.
+ */
+ public static Date toDate(Value value) {
+ return new Date(getTimestamp(value) / 1000);
+ }
+
+ /**
+ * @param entity the entity to insert
+ * @return a mutation that will insert an entity
+ */
+ public static Mutation.Builder makeInsert(Entity entity) {
+ return Mutation.newBuilder().setInsert(entity);
+ }
+
+ /**
+ * @param entity the entity to update
+ * @return a mutation that will update an entity
+ */
+ public static Mutation.Builder makeUpdate(Entity entity) {
+ return Mutation.newBuilder().setUpdate(entity);
+ }
+
+ /**
+ * @param entity the entity to upsert
+ * @return a mutation that will upsert an entity
+ */
+ public static Mutation.Builder makeUpsert(Entity entity) {
+ return Mutation.newBuilder().setUpsert(entity);
+ }
+
+ /**
+ * @param key the key of the entity to delete
+ * @return a mutation that will delete an entity
+ */
+ public static Mutation.Builder makeDelete(Key key) {
+ return Mutation.newBuilder().setDelete(key);
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreOptions.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreOptions.java
new file mode 100644
index 000000000000..2c8d5e48004a
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/DatastoreOptions.java
@@ -0,0 +1,204 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.HttpRequestInitializer;
+import com.google.api.client.http.HttpTransport;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * An immutable object containing settings for the datastore.
+ *
+ * Example for connecting to a datastore:
+ *
+ *
+ * DatastoreOptions options = new DatastoreOptions.Builder()
+ * .projectId("my-project-id")
+ * .credential(DatastoreHelper.getComputeEngineCredential())
+ * .build();
+ * DatastoreFactory.get().create(options);
+ *
+ *
+ * The options should be passed to {@link DatastoreFactory#create}.
+ */
+public class DatastoreOptions {
+ private final String projectId;
+
+ private final String projectEndpoint;
+ private final String host;
+ private final String localHost;
+
+ private final HttpRequestInitializer initializer;
+
+ private final Credential credential;
+ private final HttpTransport transport;
+ public static final List SCOPES =
+ Arrays.asList("https://www.googleapis.com/auth/datastore");
+
+ DatastoreOptions(Builder b) {
+ checkArgument(
+ b.projectId != null || b.projectEndpoint != null,
+ "Either project ID or project endpoint must be provided.");
+ this.projectId = b.projectId;
+ this.projectEndpoint = b.projectEndpoint;
+ this.host = b.host;
+ this.localHost = b.localHost;
+ this.initializer = b.initializer;
+ this.credential = b.credential;
+ this.transport = b.transport;
+ }
+
+ /** Builder for {@link DatastoreOptions}. */
+ public static class Builder {
+ private static final String PROJECT_ENDPOINT_AND_PROJECT_ID_ERROR =
+ "Cannot set both project endpoint and project ID.";
+ private static final String PROJECT_ENDPOINT_AND_HOST_ERROR =
+ "Can set at most one of project endpoint, host, and local host.";
+
+ private String projectId;
+
+ private String projectEndpoint;
+ private String host;
+ private String localHost;
+ private HttpRequestInitializer initializer;
+ private Credential credential;
+ private HttpTransport transport;
+
+ public Builder() {}
+
+ public Builder(DatastoreOptions options) {
+ this.projectId = options.projectId;
+ this.projectEndpoint = options.projectEndpoint;
+ this.host = options.host;
+ this.localHost = options.localHost;
+ this.initializer = options.initializer;
+ this.credential = options.credential;
+ this.transport = options.transport;
+ }
+
+ public DatastoreOptions build() {
+ return new DatastoreOptions(this);
+ }
+
+ /** Sets the project ID used to access Cloud Datastore. */
+ public Builder projectId(String projectId) {
+ checkArgument(projectEndpoint == null, PROJECT_ENDPOINT_AND_PROJECT_ID_ERROR);
+ this.projectId = projectId;
+ return this;
+ }
+
+ /**
+ * Sets the host used to access Cloud Datastore. To connect to the Cloud Datastore Emulator, use
+ * {@link #localHost} instead.
+ */
+ public Builder host(String host) {
+ checkArgument(projectEndpoint == null && localHost == null, PROJECT_ENDPOINT_AND_HOST_ERROR);
+ if (includesScheme(host)) {
+ throw new IllegalArgumentException(
+ String.format("Host \"%s\" must not include scheme.", host));
+ }
+ this.host = host;
+ return this;
+ }
+
+ /**
+ * Configures the client to access Cloud Datastore on a local host (typically a Cloud Datastore
+ * Emulator instance). Call this method also configures the client not to attach credentials to
+ * requests.
+ */
+ public Builder localHost(String localHost) {
+ checkArgument(projectEndpoint == null && host == null, PROJECT_ENDPOINT_AND_HOST_ERROR);
+ if (includesScheme(localHost)) {
+ throw new IllegalArgumentException(
+ String.format("Local host \"%s\" must not include scheme.", localHost));
+ }
+ this.localHost = localHost;
+ return this;
+ }
+
+ /**
+ * Sets the project endpoint used to access Cloud Datastore. Prefer using {@link #projectId}
+ * and/or {@link #host}/{@link #localHost} when possible.
+ *
+ * @deprecated Use {@link #projectId} and/or {@link #host}/{@link #localHost} instead.
+ */
+ @Deprecated
+ public Builder projectEndpoint(String projectEndpoint) {
+ checkArgument(projectId == null, PROJECT_ENDPOINT_AND_PROJECT_ID_ERROR);
+ checkArgument(localHost == null && host == null, PROJECT_ENDPOINT_AND_HOST_ERROR);
+ if (!includesScheme(projectEndpoint)) {
+ throw new IllegalArgumentException(
+ String.format("Project endpoint \"%s\" must include scheme.", projectEndpoint));
+ }
+ this.projectEndpoint = projectEndpoint;
+ return this;
+ }
+
+ /** Sets the (optional) initializer to run on HTTP requests to Cloud Datastore. */
+ public Builder initializer(HttpRequestInitializer initializer) {
+ this.initializer = initializer;
+ return this;
+ }
+
+ /** Sets the Google APIs {@link Credential} used to access Cloud Datastore. */
+ public Builder credential(Credential credential) {
+ this.credential = credential;
+ return this;
+ }
+
+ /** Sets the transport used to access Cloud Datastore. */
+ public Builder transport(HttpTransport transport) {
+ this.transport = transport;
+ return this;
+ }
+
+ private static boolean includesScheme(String url) {
+ return url.startsWith("http://") || url.startsWith("https://");
+ }
+ }
+
+ public String getProjectId() {
+ return projectId;
+ }
+
+ public String getProjectEndpoint() {
+ return projectEndpoint;
+ }
+
+ public String getHost() {
+ return host;
+ }
+
+ public String getLocalHost() {
+ return localHost;
+ }
+
+ public HttpRequestInitializer getInitializer() {
+ return initializer;
+ }
+
+ public Credential getCredential() {
+ return credential;
+ }
+
+ public HttpTransport getTransport() {
+ return transport;
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/QuerySplitter.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/QuerySplitter.java
new file mode 100644
index 000000000000..beb20a05babd
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/QuerySplitter.java
@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import com.google.api.core.BetaApi;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Query;
+import com.google.protobuf.Timestamp;
+import java.util.List;
+
+/** Provides the ability to split a query into multiple shards. */
+public interface QuerySplitter {
+
+ /**
+ * Returns a list of sharded {@link Query}s for the given query.
+ *
+ * This will create up to the desired number of splits, however it may return less splits if
+ * the desired number of splits is unavailable. This will happen if the number of split points
+ * provided by the underlying Datastore is less than the desired number, which will occur if the
+ * number of results for the query is too small.
+ *
+ * @param query the query to split.
+ * @param partition the partition the query is running in.
+ * @param numSplits the desired number of splits.
+ * @param datastore the datastore to run on.
+ * @throws DatastoreException if there was a datastore error while generating query splits.
+ * @throws IllegalArgumentException if the given query or numSplits was invalid.
+ */
+ List getSplits(Query query, PartitionId partition, int numSplits, Datastore datastore)
+ throws DatastoreException;
+
+ /**
+ * Same as {@link #getSplits(Query, PartitionId, int, Datastore)} but the splits are based on
+ * {@code readTime}, and the returned sharded {@link Query}s should also be executed with {@code
+ * readTime}. Reading from a timestamp is currently a private preview feature in Datastore.
+ */
+ @BetaApi
+ default List getSplits(
+ Query query, PartitionId partition, int numSplits, Datastore datastore, Timestamp readTime)
+ throws DatastoreException {
+ throw new UnsupportedOperationException("Not implemented.");
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/QuerySplitterImpl.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/QuerySplitterImpl.java
new file mode 100644
index 000000000000..f139b7c1fc8c
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/QuerySplitterImpl.java
@@ -0,0 +1,309 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static com.google.datastore.utils.DatastoreHelper.makeAndFilter;
+
+import com.google.api.core.BetaApi;
+import com.google.datastore.v1.EntityResult;
+import com.google.datastore.v1.Filter;
+import com.google.datastore.v1.Key;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Projection;
+import com.google.datastore.v1.PropertyFilter;
+import com.google.datastore.v1.PropertyFilter.Operator;
+import com.google.datastore.v1.PropertyOrder.Direction;
+import com.google.datastore.v1.PropertyReference;
+import com.google.datastore.v1.Query;
+import com.google.datastore.v1.QueryResultBatch;
+import com.google.datastore.v1.QueryResultBatch.MoreResultsType;
+import com.google.datastore.v1.ReadOptions;
+import com.google.datastore.v1.RunQueryRequest;
+import com.google.protobuf.Timestamp;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.List;
+import javax.annotation.Nullable;
+
+/**
+ * Provides the ability to split a query into multiple shards using Cloud Datastore.
+ *
+ * This implementation of the QuerySplitter uses the __scatter__ property to gather random split
+ * points for a query.
+ */
+final class QuerySplitterImpl implements QuerySplitter {
+
+ /** The number of keys to sample for each split. * */
+ private static final int KEYS_PER_SPLIT = 32;
+
+ private static final EnumSet UNSUPPORTED_OPERATORS =
+ EnumSet.of(
+ Operator.LESS_THAN,
+ Operator.LESS_THAN_OR_EQUAL,
+ Operator.GREATER_THAN,
+ Operator.GREATER_THAN_OR_EQUAL);
+
+ static final QuerySplitter INSTANCE = new QuerySplitterImpl();
+
+ private QuerySplitterImpl() {
+ // No initialization required.
+ }
+
+ @Override
+ public List getSplits(
+ Query query, PartitionId partition, int numSplits, Datastore datastore)
+ throws DatastoreException, IllegalArgumentException {
+ return getSplitsInternal(query, partition, numSplits, datastore, null);
+ }
+
+ @BetaApi
+ @Override
+ public List getSplits(
+ Query query, PartitionId partition, int numSplits, Datastore datastore, Timestamp readTime)
+ throws DatastoreException, IllegalArgumentException {
+ return getSplitsInternal(query, partition, numSplits, datastore, readTime);
+ }
+
+ private List getSplitsInternal(
+ Query query,
+ PartitionId partition,
+ int numSplits,
+ Datastore datastore,
+ @Nullable Timestamp readTime)
+ throws DatastoreException, IllegalArgumentException {
+ List splits = new ArrayList(numSplits);
+ if (numSplits == 1) {
+ splits.add(query);
+ return splits;
+ }
+ validateQuery(query);
+ validateSplitSize(numSplits);
+
+ List scatterKeys = getScatterKeys(numSplits, query, partition, datastore, readTime);
+ Key lastKey = null;
+ for (Key nextKey : getSplitKey(scatterKeys, numSplits)) {
+ splits.add(createSplit(lastKey, nextKey, query));
+ lastKey = nextKey;
+ }
+ splits.add(createSplit(lastKey, null, query));
+ return splits;
+ }
+
+ /**
+ * Verify that the given number of splits is not out of bounds.
+ *
+ * @param numSplits the number of splits.
+ * @throws IllegalArgumentException if the split size is invalid.
+ */
+ private void validateSplitSize(int numSplits) throws IllegalArgumentException {
+ if (numSplits < 1) {
+ throw new IllegalArgumentException("The number of splits must be greater than 0.");
+ }
+ }
+
+ /**
+ * Validates that we only have allowable filters.
+ *
+ * Note that equality and ancestor filters are allowed, however they may result in inefficient
+ * sharding.
+ */
+ private void validateFilter(Filter filter) throws IllegalArgumentException {
+ switch (filter.getFilterTypeCase()) {
+ case COMPOSITE_FILTER:
+ for (Filter subFilter : filter.getCompositeFilter().getFiltersList()) {
+ validateFilter(subFilter);
+ }
+ break;
+ case PROPERTY_FILTER:
+ if (UNSUPPORTED_OPERATORS.contains(filter.getPropertyFilter().getOp())) {
+ throw new IllegalArgumentException("Query cannot have any inequality filters.");
+ }
+ break;
+ default:
+ throw new IllegalArgumentException(
+ "Unsupported filter type: " + filter.getFilterTypeCase());
+ }
+ }
+
+ /**
+ * Verifies that the given query can be properly scattered.
+ *
+ * @param query the query to verify
+ * @throws IllegalArgumentException if the query is invalid.
+ */
+ private void validateQuery(Query query) throws IllegalArgumentException {
+ if (query.getKindCount() != 1) {
+ throw new IllegalArgumentException("Query must have exactly one kind.");
+ }
+ if (query.getOrderCount() != 0) {
+ throw new IllegalArgumentException("Query cannot have any sort orders.");
+ }
+ if (query.hasFilter()) {
+ validateFilter(query.getFilter());
+ }
+ }
+
+ /**
+ * Create a new {@link Query} given the query and range.
+ *
+ * @param lastKey the previous key. If null then assumed to be the beginning.
+ * @param nextKey the next key. If null then assumed to be the end.
+ * @param query the desired query.
+ */
+ private Query createSplit(Key lastKey, Key nextKey, Query query) {
+ if (lastKey == null && nextKey == null) {
+ return query;
+ }
+ List keyFilters = new ArrayList();
+ if (query.hasFilter()) {
+ keyFilters.add(query.getFilter());
+ }
+ if (lastKey != null) {
+ Filter lowerBound =
+ DatastoreHelper.makeFilter(
+ DatastoreHelper.KEY_PROPERTY_NAME,
+ PropertyFilter.Operator.GREATER_THAN_OR_EQUAL,
+ DatastoreHelper.makeValue(lastKey))
+ .build();
+ keyFilters.add(lowerBound);
+ }
+ if (nextKey != null) {
+ Filter upperBound =
+ DatastoreHelper.makeFilter(
+ DatastoreHelper.KEY_PROPERTY_NAME,
+ PropertyFilter.Operator.LESS_THAN,
+ DatastoreHelper.makeValue(nextKey))
+ .build();
+ keyFilters.add(upperBound);
+ }
+ return Query.newBuilder(query).setFilter(makeAndFilter(keyFilters)).build();
+ }
+
+ /**
+ * Gets a list of split keys given a desired number of splits.
+ *
+ * This list will contain multiple split keys for each split. Only a single split key will be
+ * chosen as the split point, however providing multiple keys allows for more uniform sharding.
+ *
+ * @param numSplits the number of desired splits.
+ * @param query the user query.
+ * @param partition the partition to run the query in.
+ * @param datastore the datastore containing the data.
+ * @param readTime read time at which to get the split keys from the datastore.
+ * @throws com.google.datastore.utils.DatastoreException if there was an error when executing the
+ * datastore query.
+ */
+ private List getScatterKeys(
+ int numSplits,
+ Query query,
+ PartitionId partition,
+ Datastore datastore,
+ @Nullable Timestamp readTime)
+ throws DatastoreException {
+ Query.Builder scatterPointQuery = createScatterQuery(query, numSplits);
+
+ List keySplits = new ArrayList();
+
+ QueryResultBatch batch;
+ do {
+ RunQueryRequest.Builder scatterRequest =
+ RunQueryRequest.newBuilder().setPartitionId(partition).setQuery(scatterPointQuery);
+ scatterRequest.setProjectId(partition.getProjectId());
+ scatterRequest.setDatabaseId(partition.getDatabaseId());
+ if (readTime != null) {
+ scatterRequest.setReadOptions(ReadOptions.newBuilder().setReadTime(readTime).build());
+ }
+ batch = datastore.runQuery(scatterRequest.build()).getBatch();
+ for (EntityResult result : batch.getEntityResultsList()) {
+ keySplits.add(result.getEntity().getKey());
+ }
+ scatterPointQuery.setStartCursor(batch.getEndCursor());
+ scatterPointQuery
+ .getLimitBuilder()
+ .setValue(scatterPointQuery.getLimit().getValue() - batch.getEntityResultsCount());
+ } while (batch.getMoreResults() == MoreResultsType.NOT_FINISHED);
+ Collections.sort(keySplits, DatastoreHelper.getKeyComparator());
+ return keySplits;
+ }
+
+ /**
+ * Creates a scatter query from the given user query
+ *
+ * @param query the user's query.
+ * @param numSplits the number of splits to create.
+ */
+ private Query.Builder createScatterQuery(Query query, int numSplits) {
+ // TODO(pcostello): We can potentially support better splits with equality filters in our query
+ // if there exists a composite index on property, __scatter__, __key__. Until an API for
+ // metadata exists, this isn't possible. Note that ancestor and inequality queries fall into
+ // the same category.
+ Query.Builder scatterPointQuery = Query.newBuilder();
+ scatterPointQuery.addAllKind(query.getKindList());
+ scatterPointQuery.addOrder(
+ DatastoreHelper.makeOrder(DatastoreHelper.SCATTER_PROPERTY_NAME, Direction.ASCENDING));
+ // There is a split containing entities before and after each scatter entity:
+ // ||---*------*------*------*------*------*------*---|| = scatter entity
+ // If we represent each split as a region before a scatter entity, there is an extra region
+ // following the last scatter point. Thus, we do not need the scatter entities for the last
+ // region.
+ scatterPointQuery.getLimitBuilder().setValue((numSplits - 1) * KEYS_PER_SPLIT);
+ scatterPointQuery.addProjection(
+ Projection.newBuilder().setProperty(PropertyReference.newBuilder().setName("__key__")));
+ return scatterPointQuery;
+ }
+
+ /**
+ * Given a list of keys and a number of splits find the keys to split on.
+ *
+ * @param keys the list of keys.
+ * @param numSplits the number of splits.
+ */
+ private Iterable getSplitKey(List keys, int numSplits) {
+ // If the number of keys is less than the number of splits, we are limited in the number of
+ // splits we can make.
+ if (keys.size() < numSplits - 1) {
+ return keys;
+ }
+
+ // Calculate the number of keys per split. This should be KEYS_PER_SPLIT, but may
+ // be less if there are not KEYS_PER_SPLIT * (numSplits - 1) scatter entities.
+ //
+ // Consider the following dataset, where - represents an entity and * represents an entity
+ // that is returned as a scatter entity:
+ // ||---*-----*----*-----*-----*------*----*----||
+ // If we want 4 splits in this data, the optimal split would look like:
+ // ||---*-----*----*-----*-----*------*----*----||
+ // | | |
+ // The scatter keys in the last region are not useful to us, so we never request them:
+ // ||---*-----*----*-----*-----*------*---------||
+ // | | |
+ // With 6 scatter keys we want to set scatter points at indexes: 1, 3, 5.
+ //
+ // We keep this as a double so that any "fractional" keys per split get distributed throughout
+ // the splits and don't make the last split significantly larger than the rest.
+ double numKeysPerSplit = Math.max(1.0, ((double) keys.size()) / (numSplits - 1));
+
+ List keysList = new ArrayList(numSplits - 1);
+ // Grab the last sample for each split, otherwise the first split will be too small.
+ for (int i = 1; i < numSplits; i++) {
+ int splitIndex = (int) Math.round(i * numKeysPerSplit) - 1;
+ keysList.add(keys.get(splitIndex));
+ }
+
+ return keysList;
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/RemoteRpc.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/RemoteRpc.java
new file mode 100644
index 000000000000..4d92ef6bce1b
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/RemoteRpc.java
@@ -0,0 +1,239 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import com.google.api.client.http.*;
+import com.google.api.client.http.protobuf.ProtoHttpContent;
+import com.google.api.client.util.IOUtils;
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.Strings;
+import com.google.protobuf.MessageLite;
+import com.google.rpc.Code;
+import com.google.rpc.Status;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.SocketTimeoutException;
+import java.nio.charset.Charset;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.logging.Logger;
+
+/**
+ * An RPC transport that sends protocol buffers over HTTP.
+ *
+ * This class is thread-safe.
+ */
+class RemoteRpc {
+ private static final Logger logger = Logger.getLogger(RemoteRpc.class.getName());
+
+ @VisibleForTesting static final String API_FORMAT_VERSION_HEADER = "X-Goog-Api-Format-Version";
+ private static final String API_FORMAT_VERSION = "2";
+
+ @VisibleForTesting static final String X_GOOG_REQUEST_PARAMS_HEADER = "x-goog-request-params";
+
+ private final HttpRequestFactory client;
+ private final HttpRequestInitializer initializer;
+ private final String url;
+ private final AtomicInteger rpcCount = new AtomicInteger(0);
+ // Not final - so it can be set/reset in Unittests
+ private static boolean enableE2EChecksum =
+ Boolean.parseBoolean(System.getenv("GOOGLE_CLOUD_DATASTORE_HTTP_ENABLE_E2E_CHECKSUM"));
+
+ RemoteRpc(HttpRequestFactory client, HttpRequestInitializer initializer, String url) {
+ this.client = client;
+ this.initializer = initializer;
+ this.url = url;
+ try {
+ resolveURL("dummyRpc");
+ } catch (Exception e) {
+ throw new IllegalArgumentException(
+ "Unable to construct RemoteRpc due to unsupported url: <" + url + ">", e);
+ }
+ }
+
+ /**
+ * Makes an RPC call using the client. Logs how long it took and any exceptions.
+ *
+ *
NOTE: The request could be an InputStream too, but the http client will need to find its
+ * length, which will require buffering it anyways.
+ *
+ * @throws com.google.datastore.utils.DatastoreException if the RPC fails.
+ */
+ public InputStream call(
+ String methodName, MessageLite request, String projectId, String databaseId)
+ throws com.google.datastore.utils.DatastoreException {
+ logger.fine("remote datastore call " + methodName);
+
+ long startTime = System.currentTimeMillis();
+ try {
+ HttpResponse httpResponse;
+ try {
+ rpcCount.incrementAndGet();
+ ProtoHttpContent payload = new ProtoHttpContent(request);
+ HttpRequest httpRequest = client.buildPostRequest(resolveURL(methodName), payload);
+ setHeaders(request, httpRequest, projectId, databaseId);
+ // Don't throw an HTTPResponseException on error. It converts the response to a String and
+ // throws away the original, whereas we need the raw bytes to parse it as a proto.
+ httpRequest.setThrowExceptionOnExecuteError(false);
+ // Datastore requests typically time out after 60s; set the read timeout to slightly longer
+ // than that by default (can be overridden via the HttpRequestInitializer).
+ httpRequest.setReadTimeout(65 * 1000);
+ if (initializer != null) {
+ initializer.initialize(httpRequest);
+ }
+ httpResponse = httpRequest.execute();
+ if (!httpResponse.isSuccessStatusCode()) {
+ try (InputStream content = httpResponse.getContent()) {
+ throw makeException(
+ url,
+ methodName,
+ content,
+ httpResponse.getContentType(),
+ httpResponse.getContentCharset(),
+ null,
+ httpResponse.getStatusCode());
+ }
+ }
+ InputStream inputStream = httpResponse.getContent();
+ return inputStream;
+ } catch (SocketTimeoutException e) {
+ throw makeException(url, methodName, Code.DEADLINE_EXCEEDED, "Deadline exceeded", e);
+ } catch (IOException e) {
+ throw makeException(url, methodName, Code.UNAVAILABLE, "I/O error", e);
+ }
+ } finally {
+ long elapsedTime = System.currentTimeMillis() - startTime;
+ logger.fine("remote datastore call " + methodName + " took " + elapsedTime + " ms");
+ }
+ }
+
+ @VisibleForTesting
+ void setHeaders(
+ MessageLite request, HttpRequest httpRequest, String projectId, String databaseId) {
+ httpRequest.getHeaders().put(API_FORMAT_VERSION_HEADER, API_FORMAT_VERSION);
+ StringBuilder builder = new StringBuilder("project_id=");
+ builder.append(projectId);
+ if (!Strings.isNullOrEmpty(databaseId)) {
+ builder.append("&database_id=");
+ builder.append(databaseId);
+ }
+ httpRequest.getHeaders().put(X_GOOG_REQUEST_PARAMS_HEADER, builder.toString());
+ }
+
+ @VisibleForTesting
+ HttpRequestFactory getClient() {
+ return client;
+ }
+
+ @VisibleForTesting
+ static void setSystemEnvE2EChecksum(boolean enableE2EChecksum) {
+ RemoteRpc.enableE2EChecksum = enableE2EChecksum;
+ }
+
+ void resetRpcCount() {
+ rpcCount.set(0);
+ }
+
+ int getRpcCount() {
+ return rpcCount.get();
+ }
+
+ public String getUrl() {
+ return url;
+ }
+
+ GenericUrl resolveURL(String path) {
+ return new GenericUrl(url + ":" + path);
+ }
+
+ HttpRequestFactory getHttpRequestFactory() {
+ return client;
+ }
+
+ public static com.google.datastore.utils.DatastoreException makeException(
+ String url, String methodName, Code code, String message, Throwable cause) {
+ logger.fine("remote datastore call " + methodName + " against " + url + " failed: " + message);
+ return new com.google.datastore.utils.DatastoreException(methodName, code, message, cause);
+ }
+
+ static DatastoreException makeException(
+ String url,
+ String methodName,
+ InputStream content,
+ String contentType,
+ Charset contentCharset,
+ Throwable cause,
+ int httpStatusCode) {
+ if (!contentType.equals("application/x-protobuf")) {
+ String responseContent;
+ try {
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ IOUtils.copy(content, out, false);
+ responseContent = out.toString(contentCharset.name());
+ } catch (IOException e) {
+ responseContent = "";
+ }
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Non-protobuf error: %s. HTTP status code was %d.", responseContent, httpStatusCode),
+ cause);
+ }
+
+ Status rpcStatus;
+ try {
+ rpcStatus = Status.parseFrom(content);
+ } catch (IOException e) {
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Unable to parse Status protocol buffer: HTTP status code was %s.", httpStatusCode),
+ e);
+ }
+
+ Code code = Code.forNumber(rpcStatus.getCode());
+ if (code == null) {
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Invalid error code: %d. Message: %s.", rpcStatus.getCode(), rpcStatus.getMessage()),
+ cause);
+ } else if (code == Code.OK) {
+ // We can end up here because there was no response body (and we successfully parsed an
+ // empty Status message). This may happen for 401s in particular due to special handling
+ // in low-level HTTP libraries.
+ if (httpStatusCode == HttpStatusCodes.STATUS_CODE_UNAUTHORIZED) {
+ return makeException(url, methodName, Code.UNAUTHENTICATED, "Unauthenticated.", cause);
+ }
+ return makeException(
+ url,
+ methodName,
+ Code.INTERNAL,
+ String.format(
+ "Unexpected OK error code with HTTP status code of %d. Message: %s.",
+ httpStatusCode, rpcStatus.getMessage()),
+ cause);
+ }
+
+ return makeException(url, methodName, code, rpcStatus.getMessage(), cause);
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/testing/MockCredential.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/testing/MockCredential.java
new file mode 100644
index 000000000000..0f2f165e08db
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/testing/MockCredential.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2026 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.datastore.utils.testing;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.HttpRequest;
+import java.io.IOException;
+
+/** Fake credential used for testing purpose. */
+public class MockCredential extends Credential {
+ public MockCredential() {
+ super(
+ new AccessMethod() {
+ @Override
+ public void intercept(HttpRequest request, String accessToken) throws IOException {}
+
+ @Override
+ public String getAccessTokenFromRequest(HttpRequest request) {
+ return "MockAccessToken";
+ }
+ });
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/testing/MockDatastoreFactory.java b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/testing/MockDatastoreFactory.java
new file mode 100644
index 000000000000..13a4539c600b
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/main/java/com/google/datastore/utils/testing/MockDatastoreFactory.java
@@ -0,0 +1,132 @@
+/*
+ * Copyright 2026 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.datastore.utils.testing;
+
+import static com.google.common.base.Preconditions.checkState;
+
+import com.google.api.client.auth.oauth2.Credential;
+import com.google.api.client.http.*;
+import com.google.api.client.testing.http.MockHttpTransport;
+import com.google.api.client.testing.http.MockLowLevelHttpRequest;
+import com.google.api.client.testing.http.MockLowLevelHttpResponse;
+import com.google.api.client.testing.util.TestableByteArrayInputStream;
+import com.google.common.collect.Iterables;
+import com.google.datastore.utils.DatastoreFactory;
+import com.google.datastore.utils.DatastoreOptions;
+import com.google.protobuf.Message;
+import com.google.rpc.Code;
+import com.google.rpc.Status;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.List;
+
+/** Fake Datastore factory used for testing purposes when a true Datastore service is not needed. */
+public class MockDatastoreFactory extends DatastoreFactory {
+ private int nextStatus;
+ private Message nextResponse;
+ private Status nextError;
+ private IOException nextException;
+
+ private String lastPath;
+ private String lastMimeType;
+ private byte[] lastBody;
+ private List lastCookies;
+ private String lastApiFormatHeaderValue;
+
+ public void setNextResponse(Message response) {
+ nextStatus = HttpStatusCodes.STATUS_CODE_OK;
+ nextResponse = response;
+ nextError = null;
+ nextException = null;
+ }
+
+ public void setNextError(int status, Code code, String message) {
+ nextStatus = status;
+ nextResponse = null;
+ nextError = makeErrorContent(message, code);
+ nextException = null;
+ }
+
+ public void setNextException(IOException exception) {
+ nextStatus = 0;
+ nextResponse = null;
+ nextError = null;
+ nextException = exception;
+ }
+
+ @Override
+ public HttpRequestFactory makeClient(DatastoreOptions options) {
+ HttpTransport transport =
+ new MockHttpTransport() {
+ @Override
+ public LowLevelHttpRequest buildRequest(String method, String url) {
+ return new MockLowLevelHttpRequest(url) {
+ @Override
+ public LowLevelHttpResponse execute() throws IOException {
+ lastPath = new GenericUrl(getUrl()).getRawPath();
+ lastMimeType = getContentType();
+ lastCookies = getHeaderValues("Cookie");
+ lastApiFormatHeaderValue =
+ Iterables.getOnlyElement(getHeaderValues("X-Goog-Api-Format-Version"));
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ getStreamingContent().writeTo(out);
+ lastBody = out.toByteArray();
+ if (nextException != null) {
+ throw nextException;
+ }
+ MockLowLevelHttpResponse response =
+ new MockLowLevelHttpResponse()
+ .setStatusCode(nextStatus)
+ .setContentType("application/x-protobuf");
+ if (nextError != null) {
+ checkState(nextResponse == null);
+ response.setContent(new TestableByteArrayInputStream(nextError.toByteArray()));
+ } else {
+ response.setContent(new TestableByteArrayInputStream(nextResponse.toByteArray()));
+ }
+ return response;
+ }
+ };
+ }
+ };
+ Credential credential = options.getCredential();
+ return transport.createRequestFactory(credential);
+ }
+
+ public String getLastPath() {
+ return lastPath;
+ }
+
+ public String getLastMimeType() {
+ return lastMimeType;
+ }
+
+ public String getLastApiFormatHeaderValue() {
+ return lastApiFormatHeaderValue;
+ }
+
+ public byte[] getLastBody() {
+ return lastBody;
+ }
+
+ public List getLastCookies() {
+ return lastCookies;
+ }
+
+ private static Status makeErrorContent(String message, Code code) {
+ return Status.newBuilder().setCode(code.getNumber()).setMessage(message).build();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreClientTest.java b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreClientTest.java
new file mode 100644
index 000000000000..c46bb1b2203e
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreClientTest.java
@@ -0,0 +1,407 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static com.google.common.truth.Truth.assertThat;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.fail;
+
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpRequestInitializer;
+import com.google.datastore.utils.testing.MockCredential;
+import com.google.datastore.utils.testing.MockDatastoreFactory;
+import com.google.datastore.v1.AllocateIdsRequest;
+import com.google.datastore.v1.AllocateIdsResponse;
+import com.google.datastore.v1.BeginTransactionRequest;
+import com.google.datastore.v1.BeginTransactionResponse;
+import com.google.datastore.v1.CommitRequest;
+import com.google.datastore.v1.CommitResponse;
+import com.google.datastore.v1.EntityResult;
+import com.google.datastore.v1.LookupRequest;
+import com.google.datastore.v1.LookupResponse;
+import com.google.datastore.v1.QueryResultBatch;
+import com.google.datastore.v1.ReserveIdsRequest;
+import com.google.datastore.v1.ReserveIdsResponse;
+import com.google.datastore.v1.RollbackRequest;
+import com.google.datastore.v1.RollbackResponse;
+import com.google.datastore.v1.RunAggregationQueryRequest;
+import com.google.datastore.v1.RunAggregationQueryResponse;
+import com.google.datastore.v1.RunQueryRequest;
+import com.google.datastore.v1.RunQueryResponse;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.Message;
+import com.google.rpc.Code;
+import java.io.IOException;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.net.SocketTimeoutException;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link DatastoreFactory} and {@link Datastore}. */
+@RunWith(JUnit4.class)
+public class DatastoreClientTest {
+ private static final String PROJECT_ID = "project-id";
+
+ private DatastoreFactory factory = new MockDatastoreFactory();
+ private DatastoreOptions.Builder options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).credential(new MockCredential());
+
+ @Test
+ public void options_NoProjectIdOrProjectEndpoint() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> factory.create(new DatastoreOptions.Builder().build()));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Either project ID or project endpoint must be provided");
+ factory.create(options.build());
+ }
+
+ @Test
+ public void options_ProjectIdAndProjectEndpoint() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .projectEndpoint(
+ "http://localhost:1234/datastore/v1beta42/projects/project-id"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Cannot set both project endpoint and project ID");
+ }
+
+ @Test
+ public void options_LocalHostAndProjectEndpoint() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .localHost("localhost:8080")
+ .projectEndpoint(
+ "http://localhost:1234/datastore/v1beta42/projects/project-id"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Can set at most one of project endpoint, host, and local host");
+ }
+
+ @Test
+ public void options_HostAndProjectEndpoint() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .host("foo-datastore.googleapis.com")
+ .projectEndpoint(
+ "http://localhost:1234/datastore/v1beta42/projects/project-id"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Can set at most one of project endpoint, host, and local host");
+ }
+
+ @Test
+ public void options_HostAndLocalHost() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ new DatastoreOptions.Builder()
+ .host("foo-datastore.googleapis.com")
+ .localHost("localhost:8080"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Can set at most one of project endpoint, host, and local host");
+ }
+
+ @Test
+ public void options_InvalidLocalHost() throws Exception {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .localHost("!not a valid url!")
+ .build()));
+ assertThat(exception).hasMessageThat().contains("Illegal character");
+ }
+
+ @Test
+ public void options_SchemeInLocalHost() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> new DatastoreOptions.Builder().localHost("http://localhost:8080"));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Local host \"http://localhost:8080\" must not include scheme");
+ }
+
+ @Test
+ public void options_InvalidHost() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .host("!not a valid url!")
+ .build()));
+ assertThat(exception).hasMessageThat().contains("Illegal character");
+ }
+
+ @Test
+ public void options_SchemeInHost() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> new DatastoreOptions.Builder().host("http://foo-datastore.googleapis.com"));
+
+ assertThat(exception)
+ .hasMessageThat()
+ .contains("Host \"http://foo-datastore.googleapis.com\" must not include scheme.");
+ }
+
+ @Test
+ public void create_NullOptions() throws Exception {
+ assertThrows(NullPointerException.class, () -> factory.create(null));
+ }
+
+ @Test
+ public void create_Host() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .host("foo-datastore.googleapis.com")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("https://foo-datastore.googleapis.com/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_LocalHost() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .localHost("localhost:8080")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("http://localhost:8080/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_LocalHostIp() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .localHost("127.0.0.1:8080")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("http://127.0.0.1:8080/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_DefaultHost() {
+ Datastore datastore =
+ factory.create(new DatastoreOptions.Builder().projectId(PROJECT_ID).build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("https://datastore.googleapis.com/v1/projects/project-id");
+ }
+
+ @Test
+ public void create_ProjectEndpoint() {
+ Datastore datastore =
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectEndpoint("http://prom-qa/datastore/v1beta42/projects/project-id")
+ .build());
+ assertThat(datastore.remoteRpc.getUrl())
+ .isEqualTo("http://prom-qa/datastore/v1beta42/projects/project-id");
+ }
+
+ @Test
+ public void create_ProjectEndpointNoScheme() {
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ factory.create(
+ new DatastoreOptions.Builder()
+ .projectEndpoint("localhost:1234/datastore/v1beta42/projects/project-id")
+ .build()));
+ assertThat(exception)
+ .hasMessageThat()
+ .contains(
+ "Project endpoint \"localhost:1234/datastore/v1beta42/projects/project-id\" must"
+ + " include scheme.");
+ }
+
+ @Test
+ public void initializer() throws Exception {
+ options.initializer(
+ new HttpRequestInitializer() {
+ @Override
+ public void initialize(HttpRequest request) {
+ request.getHeaders().setCookie("magic");
+ }
+ });
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+ AllocateIdsRequest request = AllocateIdsRequest.newBuilder().build();
+ AllocateIdsResponse response = AllocateIdsResponse.newBuilder().build();
+ mockClient.setNextResponse(response);
+ assertEquals(response, datastore.allocateIds(request));
+ assertEquals("magic", mockClient.getLastCookies().get(0));
+ }
+
+ @Test
+ public void allocateIds() throws Exception {
+ AllocateIdsRequest.Builder request = AllocateIdsRequest.newBuilder();
+ AllocateIdsResponse.Builder response = AllocateIdsResponse.newBuilder();
+ expectRpc("allocateIds", request.build(), response.build());
+ }
+
+ @Test
+ public void lookup() throws Exception {
+ LookupRequest.Builder request = LookupRequest.newBuilder();
+ LookupResponse.Builder response = LookupResponse.newBuilder();
+ expectRpc("lookup", request.build(), response.build());
+ }
+
+ @Test
+ public void beginTransaction() throws Exception {
+ BeginTransactionRequest.Builder request = BeginTransactionRequest.newBuilder();
+ BeginTransactionResponse.Builder response = BeginTransactionResponse.newBuilder();
+ response.setTransaction(ByteString.copyFromUtf8("project-id"));
+ expectRpc("beginTransaction", request.build(), response.build());
+ }
+
+ @Test
+ public void commit() throws Exception {
+ CommitRequest.Builder request = CommitRequest.newBuilder();
+ request.setTransaction(ByteString.copyFromUtf8("project-id"));
+ CommitResponse.Builder response = CommitResponse.newBuilder();
+ expectRpc("commit", request.build(), response.build());
+ }
+
+ @Test
+ public void reserveIds() throws Exception {
+ ReserveIdsRequest.Builder request = ReserveIdsRequest.newBuilder();
+ ReserveIdsResponse.Builder response = ReserveIdsResponse.newBuilder();
+ expectRpc("reserveIds", request.build(), response.build());
+ }
+
+ @Test
+ public void rollback() throws Exception {
+ RollbackRequest.Builder request = RollbackRequest.newBuilder();
+ request.setTransaction(ByteString.copyFromUtf8("project-id"));
+ RollbackResponse.Builder response = RollbackResponse.newBuilder();
+ expectRpc("rollback", request.build(), response.build());
+ }
+
+ @Test
+ public void runQuery() throws Exception {
+ RunQueryRequest.Builder request = RunQueryRequest.newBuilder();
+ request.getQueryBuilder();
+ RunQueryResponse.Builder response = RunQueryResponse.newBuilder();
+ response
+ .getBatchBuilder()
+ .setEntityResultType(EntityResult.ResultType.FULL)
+ .setMoreResults(QueryResultBatch.MoreResultsType.NOT_FINISHED);
+ expectRpc("runQuery", request.build(), response.build());
+ }
+
+ @Test
+ public void runAggregationQuery() throws Exception {
+ RunAggregationQueryRequest.Builder request = RunAggregationQueryRequest.newBuilder();
+ RunAggregationQueryResponse.Builder response = RunAggregationQueryResponse.newBuilder();
+ expectRpc("runAggregationQuery", request.build(), response.build());
+ }
+
+ private void expectRpc(String methodName, Message request, Message response) throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ mockClient.setNextResponse(response);
+ @SuppressWarnings("rawtypes")
+ Class[] methodArgs = {request.getClass()};
+ Method call = Datastore.class.getMethod(methodName, methodArgs);
+ Object[] callArgs = {request};
+ assertEquals(response, call.invoke(datastore, callArgs));
+
+ assertEquals("/v1/projects/project-id:" + methodName, mockClient.getLastPath());
+ assertEquals("application/x-protobuf", mockClient.getLastMimeType());
+ assertEquals("2", mockClient.getLastApiFormatHeaderValue());
+ assertArrayEquals(request.toByteArray(), mockClient.getLastBody());
+ assertEquals(1, datastore.getRpcCount());
+
+ datastore.resetRpcCount();
+ assertEquals(0, datastore.getRpcCount());
+
+ mockClient.setNextError(400, Code.INVALID_ARGUMENT, "oops");
+ try {
+ call.invoke(datastore, callArgs);
+ fail();
+ } catch (InvocationTargetException targetException) {
+ DatastoreException exception = (DatastoreException) targetException.getCause();
+ assertEquals(Code.INVALID_ARGUMENT, exception.getCode());
+ assertEquals(methodName, exception.getMethodName());
+ assertEquals("oops", exception.getMessage());
+ }
+
+ SocketTimeoutException socketTimeoutException = new SocketTimeoutException("ste");
+ mockClient.setNextException(socketTimeoutException);
+ try {
+ call.invoke(datastore, callArgs);
+ fail();
+ } catch (InvocationTargetException targetException) {
+ DatastoreException exception = (DatastoreException) targetException.getCause();
+ assertEquals(Code.DEADLINE_EXCEEDED, exception.getCode());
+ assertEquals(methodName, exception.getMethodName());
+ assertEquals("Deadline exceeded", exception.getMessage());
+ assertSame(socketTimeoutException, exception.getCause());
+ }
+
+ IOException ioException = new IOException("ioe");
+ mockClient.setNextException(ioException);
+ try {
+ call.invoke(datastore, callArgs);
+ fail();
+ } catch (InvocationTargetException targetException) {
+ DatastoreException exception = (DatastoreException) targetException.getCause();
+ assertEquals(Code.UNAVAILABLE, exception.getCode());
+ assertEquals(methodName, exception.getMethodName());
+ assertEquals("I/O error", exception.getMessage());
+ assertSame(ioException, exception.getCause());
+ }
+
+ assertEquals(3, datastore.getRpcCount());
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreFactoryTest.java b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreFactoryTest.java
new file mode 100644
index 000000000000..51446f981a9f
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreFactoryTest.java
@@ -0,0 +1,93 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertTrue;
+
+import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
+import com.google.api.client.http.HttpRequestFactory;
+import com.google.api.client.http.javanet.NetHttpTransport;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Test for {@link DatastoreFactory}. */
+@RunWith(JUnit4.class)
+public class DatastoreFactoryTest {
+ private static final String PROJECT_ID = "project-id";
+
+ private DatastoreFactory factory = DatastoreFactory.get();
+
+ /**
+ * Without specifying a credential or transport, the factory will create a default transport on
+ * its own.
+ */
+ @Test
+ public void makeClient_Default() {
+ DatastoreOptions options = new DatastoreOptions.Builder().projectId(PROJECT_ID).build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertNotNull(f.getTransport());
+ assertTrue(f.getTransport() instanceof NetHttpTransport);
+ }
+
+ /**
+ * Specifying a credential, but not a transport, the factory will use the transport from the
+ * credential.
+ */
+ @Test
+ public void makeClient_WithCredential() {
+ NetHttpTransport transport = new NetHttpTransport();
+ GoogleCredential credential = new GoogleCredential.Builder().setTransport(transport).build();
+ DatastoreOptions options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).credential(credential).build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertEquals(transport, f.getTransport());
+ }
+
+ /** Specifying a transport, but not a credential, the factory will use the transport specified. */
+ @Test
+ public void makeClient_WithTransport() {
+ NetHttpTransport transport = new NetHttpTransport();
+ DatastoreOptions options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).transport(transport).build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertEquals(transport, f.getTransport());
+ }
+
+ /**
+ * Specifying both credential and transport, the factory will use the transport specified and not
+ * the one in the credential.
+ */
+ @Test
+ public void makeClient_WithCredentialTransport() {
+ NetHttpTransport credTransport = new NetHttpTransport();
+ NetHttpTransport transport = new NetHttpTransport();
+ GoogleCredential credential =
+ new GoogleCredential.Builder().setTransport(credTransport).build();
+ DatastoreOptions options =
+ new DatastoreOptions.Builder()
+ .projectId(PROJECT_ID)
+ .credential(credential)
+ .transport(transport)
+ .build();
+ HttpRequestFactory f = factory.makeClient(options);
+ assertNotSame(credTransport, f.getTransport());
+ assertEquals(transport, f.getTransport());
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreHelperTest.java b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreHelperTest.java
new file mode 100644
index 000000000000..db0949800f2d
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/DatastoreHelperTest.java
@@ -0,0 +1,317 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static com.google.datastore.utils.DatastoreHelper.*;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
+
+import com.google.datastore.v1.Key;
+import com.google.datastore.v1.PartitionId;
+import com.google.datastore.v1.Value;
+import com.google.datastore.v1.Value.ValueTypeCase;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.Timestamp;
+import java.util.Date;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link DatastoreHelper}. */
+@RunWith(JUnit4.class)
+public class DatastoreHelperTest {
+
+ private static final Key PARENT =
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Parent").setId(23L)).build();
+ private static final Key GRANDPARENT =
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Grandparent").setId(24L))
+ .build();
+ private static final Key CHILD =
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Child").setId(26L)).build();
+
+ @Test
+ public void testMakeKey_BadTypeForKind() {
+ try {
+ DatastoreHelper.makeKey(new Object());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+
+ @Test
+ public void testMakeKey_BadTypeForNameId() {
+ try {
+ DatastoreHelper.makeKey("kind", new Object());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+
+ @Test
+ public void testMakeKey_Empty() {
+ assertEquals(Key.newBuilder().build(), DatastoreHelper.makeKey().build());
+ }
+
+ @Test
+ public void testMakeKey_Incomplete() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo")).build(),
+ makeKey("Foo").build());
+ }
+
+ @Test
+ public void testMakeKey_IdInt() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setId(1)).build(),
+ makeKey("Foo", 1).build());
+ }
+
+ @Test
+ public void testMakeKey_IdLong() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setId(1)).build(),
+ makeKey("Foo", 1L).build());
+ }
+
+ @Test
+ public void testMakeKey_IdShort() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setId(1)).build(),
+ makeKey("Foo", (short) 1).build());
+ }
+
+ @Test
+ public void testMakeKey_Name() {
+ assertEquals(
+ Key.newBuilder().addPath(Key.PathElement.newBuilder().setKind("Foo").setName("hi")).build(),
+ makeKey("Foo", "hi").build());
+ }
+
+ @Test
+ public void testMakeKey_KindNameKind() {
+ assertEquals(
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Foo").setName("hi"))
+ .addPath(Key.PathElement.newBuilder().setKind("Bar"))
+ .build(),
+ makeKey("Foo", "hi", "Bar").build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKind() {
+ // 1 key at the beginning of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(PARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Child"))
+ .build(),
+ makeKey(PARENT, "Child").build());
+ }
+
+ @Test
+ public void testMakeKey_KindIdKeyKind() {
+ // 1 key in the middle of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Grandparent").setId(24L))
+ .addPath(PARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Child"))
+ .build(),
+ makeKey("Grandparent", 24L, PARENT, "Child").build());
+ }
+
+ @Test
+ public void testMakeKey_KindIdKey() {
+ // 1 key at the end of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(Key.PathElement.newBuilder().setKind("Grandparent").setId(24L))
+ .addPath(PARENT.getPath(0))
+ .build(),
+ makeKey("Grandparent", 24L, PARENT).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKindIdKey() {
+ // 1 key at the beginning and 1 key at the end of the series
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Parent").setId(23L))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(GRANDPARENT, "Parent", 23, CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_Key() {
+ // Just 1 key
+ assertEquals(Key.newBuilder().addPath(CHILD.getPath(0)).build(), makeKey(CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKey() {
+ // Just 2 keys
+ assertEquals(
+ Key.newBuilder().addPath(PARENT.getPath(0)).addPath(CHILD.getPath(0)).build(),
+ makeKey(PARENT, CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyKeyKey() {
+ // Just 3 keys
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(GRANDPARENT, PARENT, CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_KeyMultiLevelKey() {
+ // 1 key with 2 elements
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(GRANDPARENT, makeKey(PARENT, CHILD).build()).build());
+ }
+
+ @Test
+ public void testMakeKey_MultiLevelKeyKey() {
+ // 1 key with 2 elements
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(makeKey(GRANDPARENT, PARENT).build(), CHILD).build());
+ }
+
+ @Test
+ public void testMakeKey_MultiLevelKey() {
+ // 1 key with 3 elements
+ assertEquals(
+ Key.newBuilder()
+ .addPath(GRANDPARENT.getPath(0))
+ .addPath(PARENT.getPath(0))
+ .addPath(CHILD.getPath(0))
+ .build(),
+ makeKey(makeKey(GRANDPARENT, PARENT, CHILD).build()).build());
+ }
+
+ @Test
+ public void testMakeKey_PartitionId() {
+ PartitionId partitionId = PartitionId.newBuilder().setNamespaceId("namespace-id").build();
+ Key parent = PARENT.toBuilder().setPartitionId(partitionId).build();
+ assertEquals(
+ Key.newBuilder()
+ .setPartitionId(partitionId)
+ .addPath(PARENT.getPath(0))
+ .addPath(Key.PathElement.newBuilder().setKind("Child"))
+ .build(),
+ makeKey(parent, "Child").build());
+ }
+
+ @Test
+ public void testMakeKey_NonMatchingPartitionId2() {
+ PartitionId partitionId1 = PartitionId.newBuilder().setNamespaceId("namespace-id").build();
+ PartitionId partitionId2 =
+ PartitionId.newBuilder().setNamespaceId("another-namespace-id").build();
+ try {
+ makeKey(
+ PARENT.toBuilder().setPartitionId(partitionId1).build(),
+ CHILD.toBuilder().setPartitionId(partitionId2).build());
+ fail("expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+
+ @Test
+ public void testMakeTimestampValue() throws Exception {
+ // Test cases with nanos == 0.
+ assertConversion(-50_000, -50, 0);
+ assertConversion(-1_000, -1, 0);
+ assertConversion(0, 0, 0);
+ assertConversion(1_000, 1, 0);
+ assertConversion(2_000, 2, 0);
+ assertConversion(100_000, 100, 0);
+
+ // Test cases with nanos % 1_000_000 == 0 (no loss of precision).
+ assertConversion(2, 0, 2_000_000);
+ assertConversion(1_003, 1, 3_000_000);
+ assertConversion(2_005, 2, 5_000_000);
+
+ // Timestamp specification requires that nanos >= 0 even if the timestamp
+ // is before the epoch.
+ assertConversion(0, 0, 0);
+ assertConversion(-250, -1, 750_000_000); // 1/4 second before epoch
+ assertConversion(-500, -1, 500_000_000); // 1/2 second before epoch
+ assertConversion(-750, -1, 250_000_000); // 3/4 second before epoch
+
+ // If nanos % 1_000_000 != 0, precision is lost (via truncation) when
+ // converting to milliseconds.
+ assertTimestampToMilliseconds(3_100, 3, 100_000_999);
+ assertMillisecondsToTimestamp(3_100, 3, 100_000_000);
+ assertTimestampToMilliseconds(5_999, 5, 999_999_999);
+ assertMillisecondsToTimestamp(5_999, 5, 999_000_000);
+ assertTimestampToMilliseconds(7_100, 7, 100_000_001);
+ assertMillisecondsToTimestamp(7_100, 7, 100_000_000);
+ }
+
+ private void assertConversion(long millis, long seconds, int nanos) {
+ assertMillisecondsToTimestamp(millis, seconds, nanos);
+ assertTimestampToMilliseconds(millis, seconds, nanos);
+ }
+
+ private void assertMillisecondsToTimestamp(long millis, long seconds, long nanos) {
+ Value timestampValue = makeValue(new Date(millis)).build();
+ assertEquals(ValueTypeCase.TIMESTAMP_VALUE, timestampValue.getValueTypeCase());
+ assertEquals(seconds, timestampValue.getTimestampValue().getSeconds());
+ assertEquals(nanos, timestampValue.getTimestampValue().getNanos());
+ }
+
+ private void assertTimestampToMilliseconds(long millis, long seconds, int nanos) {
+ Value.Builder value =
+ Value.newBuilder()
+ .setTimestampValue(Timestamp.newBuilder().setSeconds(seconds).setNanos(nanos));
+ assertEquals(millis, DatastoreHelper.toDate(value.build()).getTime());
+ }
+
+ @Test
+ public void testProjectionHandling() {
+ assertEquals(
+ ByteString.copyFromUtf8("hi"), getByteString(makeValue("hi").setMeaning(18).build()));
+ try {
+ getByteString(makeValue("hi").build());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+
+ assertEquals(new Date(1), toDate(makeValue(1000).setMeaning(18).build()));
+ try {
+ toDate(makeValue(1000).build());
+ fail("Expected IllegalArgumentException");
+ } catch (IllegalArgumentException expected) {
+ }
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/QuerySplitterTest.java b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/QuerySplitterTest.java
new file mode 100644
index 000000000000..d173576ae6a2
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/QuerySplitterTest.java
@@ -0,0 +1,365 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static com.google.common.truth.Truth.assertThat;
+import static com.google.datastore.utils.DatastoreHelper.*;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertThrows;
+
+import com.google.datastore.utils.testing.MockCredential;
+import com.google.datastore.utils.testing.MockDatastoreFactory;
+import com.google.datastore.v1.*;
+import com.google.datastore.v1.EntityResult.ResultType;
+import com.google.datastore.v1.PropertyFilter.Operator;
+import com.google.datastore.v1.PropertyOrder.Direction;
+import com.google.datastore.v1.QueryResultBatch.MoreResultsType;
+import com.google.protobuf.Int32Value;
+import com.google.protobuf.Timestamp;
+import java.util.List;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for {@link com.google.datastore.utils.QuerySplitterImpl}. */
+@RunWith(JUnit4.class)
+public class QuerySplitterTest {
+ private static final String PROJECT_ID = "project-id";
+ private static final PartitionId PARTITION =
+ PartitionId.newBuilder().setProjectId(PROJECT_ID).build();
+ private static final String KIND = "test-kind";
+
+ private DatastoreFactory factory = new MockDatastoreFactory();
+ private com.google.datastore.utils.DatastoreOptions.Builder options =
+ new DatastoreOptions.Builder().projectId(PROJECT_ID).credential(new MockCredential());
+
+ private Filter propertyFilter = makeFilter("foo", Operator.EQUAL, makeValue("value")).build();
+
+ private Query query =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .setFilter(propertyFilter)
+ .build();
+
+ private Query splitQuery =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .addOrder(makeOrder("__scatter__", Direction.ASCENDING))
+ .addProjection(Projection.newBuilder().setProperty(makePropertyReference("__key__")))
+ .build();
+
+ private Key splitKey0 = makeKey(KIND, String.format("%05d", 1)).setPartitionId(PARTITION).build();
+ private Key splitKey1 =
+ makeKey(KIND, String.format("%05d", 101)).setPartitionId(PARTITION).build();
+ private Key splitKey2 =
+ makeKey(KIND, String.format("%05d", 201)).setPartitionId(PARTITION).build();
+ private Key splitKey3 =
+ makeKey(KIND, String.format("%05d", 301)).setPartitionId(PARTITION).build();
+
+ @Test
+ public void disallowsSortOrder() {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ Query queryWithOrder =
+ query.toBuilder().addOrder(makeOrder("bar", Direction.ASCENDING)).build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ queryWithOrder, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query cannot have any sort orders.");
+ }
+
+ @Test
+ public void disallowsMultipleKinds() {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ Query queryWithMultipleKinds =
+ query.toBuilder()
+ .addKind(KindExpression.newBuilder().setName("another-kind").build())
+ .build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ queryWithMultipleKinds, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query must have exactly one kind.");
+ }
+
+ @Test
+ public void disallowsKindlessQuery() {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ Query kindlessQuery = query.toBuilder().clearKind().build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ kindlessQuery, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query must have exactly one kind.");
+ }
+
+ @Test
+ public void disallowsInequalityFilter() {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ Query queryWithInequality =
+ query.toBuilder()
+ .setFilter(makeFilter("foo", Operator.GREATER_THAN, makeValue("value")))
+ .build();
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ queryWithInequality, PARTITION, 2, datastore));
+ assertThat(exception).hasMessageThat().contains("Query cannot have any inequality filters.");
+ }
+
+ @Test
+ public void splitsMustBePositive() {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ IllegalArgumentException exception =
+ assertThrows(
+ IllegalArgumentException.class,
+ () ->
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ query, PARTITION, 0, datastore));
+ assertThat(exception).hasMessageThat().contains("The number of splits must be greater than 0.");
+ }
+
+ @Test
+ public void getSplits() throws Exception {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .addEntityResults(makeKeyOnlyEntity(splitKey1))
+ .addEntityResults(makeKeyOnlyEntity(splitKey2))
+ .addEntityResults(makeKeyOnlyEntity(splitKey3))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ List splittedQueries =
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ query, PARTITION, 3, datastore);
+
+ assertThat(splittedQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey1))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey1, splitKey3))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey3, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(PARTITION)
+ .setProjectId(PROJECT_ID)
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(2 * 32).build()))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ @Test
+ public void getSplitsWithDatabaseId() throws Exception {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ PartitionId partition =
+ PartitionId.newBuilder().setProjectId(PROJECT_ID).setDatabaseId("test-database").build();
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .addEntityResults(makeKeyOnlyEntity(splitKey1))
+ .addEntityResults(makeKeyOnlyEntity(splitKey2))
+ .addEntityResults(makeKeyOnlyEntity(splitKey3))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ List splitQueries =
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ query, partition, 3, datastore);
+
+ assertThat(splitQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey1))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey1, splitKey3))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey3, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(partition)
+ .setProjectId(PROJECT_ID)
+ .setDatabaseId("test-database")
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(2 * 32).build()))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ @Test
+ public void notEnoughSplits() throws Exception {
+ com.google.datastore.utils.Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ List splittedQueries =
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ query, PARTITION, 100, datastore);
+
+ assertThat(splittedQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey0))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey0, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(PARTITION)
+ .setProjectId(PROJECT_ID)
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(99 * 32).build()))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ @Test
+ public void getSplits_withReadTime() throws Exception {
+ Datastore datastore = factory.create(options.build());
+ MockDatastoreFactory mockClient = (MockDatastoreFactory) factory;
+
+ RunQueryResponse splitQueryResponse =
+ RunQueryResponse.newBuilder()
+ .setQuery(splitQuery)
+ .setBatch(
+ QueryResultBatch.newBuilder()
+ .setEntityResultType(ResultType.KEY_ONLY)
+ .setMoreResults(MoreResultsType.NO_MORE_RESULTS)
+ .addEntityResults(makeKeyOnlyEntity(splitKey0))
+ .addEntityResults(makeKeyOnlyEntity(splitKey1))
+ .addEntityResults(makeKeyOnlyEntity(splitKey2))
+ .addEntityResults(makeKeyOnlyEntity(splitKey3))
+ .build())
+ .build();
+
+ mockClient.setNextResponse(splitQueryResponse);
+
+ Timestamp readTime = Timestamp.newBuilder().setSeconds(1654651341L).build();
+
+ List splittedQueries =
+ com.google.datastore.utils.QuerySplitterImpl.INSTANCE.getSplits(
+ query, PARTITION, 3, datastore, readTime);
+
+ assertThat(splittedQueries)
+ .containsExactly(
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, null, splitKey1))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey1, splitKey3))
+ .build(),
+ query.toBuilder()
+ .setFilter(makeFilterWithKeyRange(propertyFilter, splitKey3, null))
+ .build());
+
+ RunQueryRequest expectedSplitQueryRequest =
+ RunQueryRequest.newBuilder()
+ .setPartitionId(PARTITION)
+ .setProjectId(PROJECT_ID)
+ .setQuery(
+ splitQuery.toBuilder().setLimit(Int32Value.newBuilder().setValue(2 * 32).build()))
+ .setReadOptions(ReadOptions.newBuilder().setReadTime(readTime))
+ .build();
+
+ assertArrayEquals(expectedSplitQueryRequest.toByteArray(), mockClient.getLastBody());
+ }
+
+ private static EntityResult makeKeyOnlyEntity(Key key) {
+ return EntityResult.newBuilder().setEntity(Entity.newBuilder().setKey(key).build()).build();
+ }
+
+ private static Filter makeFilterWithKeyRange(Filter originalFilter, Key startKey, Key endKey) {
+ Filter startKeyFilter =
+ startKey == null
+ ? null
+ : makeFilter("__key__", Operator.GREATER_THAN_OR_EQUAL, makeValue(startKey)).build();
+
+ Filter endKeyFilter =
+ endKey == null
+ ? null
+ : makeFilter("__key__", Operator.LESS_THAN, makeValue(endKey)).build();
+
+ if (startKeyFilter == null && endKeyFilter == null) {
+ throw new IllegalArgumentException();
+ }
+
+ if (startKeyFilter != null && endKeyFilter == null) {
+ return makeAndFilter(originalFilter, startKeyFilter).build();
+ }
+
+ if (startKeyFilter == null && endKeyFilter != null) {
+ return makeAndFilter(originalFilter, endKeyFilter).build();
+ }
+
+ return makeAndFilter(originalFilter, startKeyFilter, endKeyFilter).build();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/RemoteRpcTest.java b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/RemoteRpcTest.java
new file mode 100644
index 000000000000..09e750d0712a
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/RemoteRpcTest.java
@@ -0,0 +1,341 @@
+/*
+ * Copyright 2026 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.datastore.utils;
+
+import static org.junit.Assert.*;
+
+import com.google.api.client.http.HttpRequest;
+import com.google.api.client.http.HttpTransport;
+import com.google.api.client.http.LowLevelHttpRequest;
+import com.google.api.client.http.LowLevelHttpResponse;
+import com.google.api.client.http.protobuf.ProtoHttpContent;
+import com.google.api.client.util.Charsets;
+import com.google.datastore.v1.BeginTransactionResponse;
+import com.google.datastore.v1.RollbackRequest;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.MessageLite;
+import com.google.rpc.Code;
+import com.google.rpc.Status;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.zip.GZIPOutputStream;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Test for {@link RemoteRpc}. */
+@RunWith(JUnit4.class)
+public class RemoteRpcTest {
+
+ private static final String METHOD_NAME = "methodName";
+
+ @Test
+ public void testException() {
+ Status statusProto =
+ Status.newBuilder()
+ .setCode(Code.UNAUTHENTICATED_VALUE)
+ .setMessage("The request does not have valid authentication credentials.")
+ .build();
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream(statusProto.toByteArray()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.UNAUTHENTICATED, exception.getCode());
+ assertEquals(
+ "The request does not have valid authentication credentials.", exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testInvalidProtoException() {
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream("".getBytes()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.INTERNAL, exception.getCode());
+ assertEquals(
+ "Unable to parse Status protocol buffer: HTTP status code was 401.",
+ exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testEmptyProtoException() {
+ Status statusProto = Status.newBuilder().build();
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream(statusProto.toByteArray()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 404);
+ assertEquals(Code.INTERNAL, exception.getCode());
+ assertEquals(
+ "Unexpected OK error code with HTTP status code of 404. Message: .",
+ exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testEmptyProtoExceptionUnauthenticated() {
+ Status statusProto = Status.newBuilder().build();
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream(statusProto.toByteArray()),
+ "application/x-protobuf",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.UNAUTHENTICATED, exception.getCode());
+ assertEquals("Unauthenticated.", exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testPlainTextException() {
+ DatastoreException exception =
+ RemoteRpc.makeException(
+ "url",
+ METHOD_NAME,
+ new ByteArrayInputStream("Text Error".getBytes()),
+ "text/plain",
+ Charsets.UTF_8,
+ new RuntimeException(),
+ 401);
+ assertEquals(Code.INTERNAL, exception.getCode());
+ assertEquals(
+ "Non-protobuf error: Text Error. HTTP status code was 401.", exception.getMessage());
+ assertEquals(METHOD_NAME, exception.getMethodName());
+ }
+
+ @Test
+ public void testGzip() throws IOException, DatastoreException {
+ BeginTransactionResponse response = newBeginTransactionResponse();
+ InjectedTestValues injectedTestValues =
+ new InjectedTestValues(gzip(response), new byte[1], true);
+ RemoteRpc rpc = newRemoteRpc(injectedTestValues);
+
+ InputStream is =
+ rpc.call("beginTransaction", BeginTransactionResponse.getDefaultInstance(), "", "");
+ BeginTransactionResponse parsedResponse = BeginTransactionResponse.parseFrom(is);
+ is.close();
+
+ assertEquals(response, parsedResponse);
+ // Check that the underlying stream is exhausted.
+ assertEquals(-1, injectedTestValues.inputStream.read());
+ }
+
+ @Test
+ public void testHttpHeaders_apiFormat() throws IOException {
+ String projectId = "project-id";
+ MessageLite request =
+ RollbackRequest.newBuilder().setTransaction(ByteString.copyFromUtf8(projectId)).build();
+ RemoteRpc rpc =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest =
+ rpc.getClient().buildPostRequest(rpc.resolveURL("blah"), new ProtoHttpContent(request));
+ rpc.setHeaders(request, httpRequest, projectId, "");
+ assertNotNull(
+ httpRequest.getHeaders().getFirstHeaderStringValue(RemoteRpc.API_FORMAT_VERSION_HEADER));
+ }
+
+ @Test
+ public void testHttpHeaders_prefixHeader() throws IOException {
+ String projectId = "my-project";
+ String databaseId = "my-db";
+ MessageLite request =
+ RollbackRequest.newBuilder()
+ .setTransaction(ByteString.copyFromUtf8(projectId))
+ .setDatabaseId(databaseId)
+ .build();
+ RemoteRpc rpc =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest =
+ rpc.getClient().buildPostRequest(rpc.resolveURL("blah"), new ProtoHttpContent(request));
+ rpc.setHeaders(request, httpRequest, projectId, databaseId);
+ assertEquals(
+ "project_id=my-project&database_id=my-db",
+ httpRequest.getHeaders().get(RemoteRpc.X_GOOG_REQUEST_PARAMS_HEADER));
+
+ MessageLite request2 =
+ RollbackRequest.newBuilder().setTransaction(ByteString.copyFromUtf8(projectId)).build();
+ RemoteRpc rpc2 =
+ newRemoteRpc(
+ new InjectedTestValues(gzip(newBeginTransactionResponse()), new byte[1], true));
+ HttpRequest httpRequest2 =
+ rpc2.getClient().buildPostRequest(rpc2.resolveURL("blah"), new ProtoHttpContent(request2));
+ rpc2.setHeaders(request, httpRequest2, projectId, "");
+ assertEquals(
+ "project_id=my-project",
+ httpRequest2.getHeaders().get(RemoteRpc.X_GOOG_REQUEST_PARAMS_HEADER));
+ }
+
+ private static BeginTransactionResponse newBeginTransactionResponse() {
+ return BeginTransactionResponse.newBuilder()
+ .setTransaction(ByteString.copyFromUtf8("blah-blah-blah"))
+ .build();
+ }
+
+ private static RemoteRpc newRemoteRpc(InjectedTestValues injectedTestValues) {
+ return new RemoteRpc(
+ new MyHttpTransport(injectedTestValues).createRequestFactory(),
+ null,
+ "https://www.example.com/v1/projects/p");
+ }
+
+ private byte[] gzip(BeginTransactionResponse response) throws IOException {
+ ByteArrayOutputStream bytesOut = new ByteArrayOutputStream();
+ try (GZIPOutputStream gzipOut = new GZIPOutputStream(bytesOut)) {
+ response.writeTo(gzipOut);
+ }
+ return bytesOut.toByteArray();
+ }
+
+ private static class InjectedTestValues {
+ private final InputStream inputStream;
+ private final int contentLength;
+ private final boolean isGzip;
+
+ public InjectedTestValues(byte[] messageBytes, byte[] additionalBytes, boolean isGzip) {
+ byte[] allBytes = concat(messageBytes, additionalBytes);
+ this.inputStream = new ByteArrayInputStream(allBytes);
+ this.contentLength = allBytes.length;
+ this.isGzip = isGzip;
+ }
+
+ private static byte[] concat(byte[] a, byte[] b) {
+ byte[] c = new byte[a.length + b.length];
+ System.arraycopy(a, 0, c, 0, a.length);
+ System.arraycopy(b, 0, c, a.length, b.length);
+ return c;
+ }
+ }
+
+ /** {@link HttpTransport} that allows injection of the returned {@link LowLevelHttpRequest}. */
+ private static class MyHttpTransport extends HttpTransport {
+
+ private final InjectedTestValues injectedTestValues;
+
+ public MyHttpTransport(InjectedTestValues injectedTestValues) {
+ this.injectedTestValues = injectedTestValues;
+ }
+
+ @Override
+ protected LowLevelHttpRequest buildRequest(String method, String url) throws IOException {
+ return new MyLowLevelHttpRequest(injectedTestValues);
+ }
+ }
+
+ /**
+ * {@link LowLevelHttpRequest} that allows injection of the returned {@link LowLevelHttpResponse}.
+ */
+ private static class MyLowLevelHttpRequest extends LowLevelHttpRequest {
+
+ private final InjectedTestValues injectedTestValues;
+
+ public MyLowLevelHttpRequest(InjectedTestValues injectedTestValues) {
+ this.injectedTestValues = injectedTestValues;
+ }
+
+ @Override
+ public void addHeader(String name, String value) throws IOException {
+ // Do nothing.
+ }
+
+ @Override
+ public LowLevelHttpResponse execute() throws IOException {
+ return new MyLowLevelHttpResponse(injectedTestValues);
+ }
+ }
+
+ /** {@link LowLevelHttpResponse} that allows injected properties. */
+ private static class MyLowLevelHttpResponse extends LowLevelHttpResponse {
+
+ private final InjectedTestValues injectedTestValues;
+
+ public MyLowLevelHttpResponse(InjectedTestValues injectedTestValues) {
+ this.injectedTestValues = injectedTestValues;
+ }
+
+ @Override
+ public InputStream getContent() throws IOException {
+ return injectedTestValues.inputStream;
+ }
+
+ @Override
+ public String getContentEncoding() throws IOException {
+ return injectedTestValues.isGzip ? "gzip" : "";
+ }
+
+ @Override
+ public long getContentLength() throws IOException {
+ return injectedTestValues.contentLength;
+ }
+
+ @Override
+ public String getContentType() throws IOException {
+ return "application/x-protobuf";
+ }
+
+ @Override
+ public String getStatusLine() throws IOException {
+ return null;
+ }
+
+ @Override
+ public int getStatusCode() throws IOException {
+ return 200;
+ }
+
+ @Override
+ public String getReasonPhrase() throws IOException {
+ return null;
+ }
+
+ @Override
+ public int getHeaderCount() throws IOException {
+ return 0;
+ }
+
+ @Override
+ public String getHeaderName(int index) throws IOException {
+ return null;
+ }
+
+ @Override
+ public String getHeaderValue(int index) throws IOException {
+ return null;
+ }
+ }
+}
diff --git a/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/it/ITDatastoreProtoClientTest.java b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/it/ITDatastoreProtoClientTest.java
new file mode 100644
index 000000000000..ae983cb9557e
--- /dev/null
+++ b/java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/it/ITDatastoreProtoClientTest.java
@@ -0,0 +1,90 @@
+/*
+ * Copyright 2026 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.datastore.utils.it;
+
+import static com.google.datastore.utils.DatastoreHelper.makeFilter;
+import static com.google.datastore.utils.DatastoreHelper.makeValue;
+
+import com.google.common.truth.Truth;
+import com.google.datastore.utils.Datastore;
+import com.google.datastore.utils.DatastoreException;
+import com.google.datastore.utils.DatastoreHelper;
+import com.google.datastore.v1.*;
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+import java.util.List;
+import org.junit.Before;
+import org.junit.Test;
+
+public class ITDatastoreProtoClientTest {
+
+ private static Datastore DATASTORE;
+
+ private static PartitionId PARTITION;
+
+ private static final String KIND = "test-kind";
+ private static final String PROJECT_ID = System.getenv(DatastoreHelper.PROJECT_ID_ENV_VAR);
+
+ @Before
+ public void setUp() throws GeneralSecurityException, IOException {
+ DATASTORE = DatastoreHelper.getDatastoreFromEnv();
+ }
+
+ @Test
+ public void testQuerySplitterWithDefaultDb() throws DatastoreException {
+ Filter propertyFilter =
+ makeFilter("foo", PropertyFilter.Operator.EQUAL, makeValue("value")).build();
+ Query query =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .setFilter(propertyFilter)
+ .build();
+
+ PARTITION = PartitionId.newBuilder().setProjectId(PROJECT_ID).build();
+
+ List splits =
+ DatastoreHelper.getQuerySplitter().getSplits(query, PARTITION, 2, DATASTORE);
+ Truth.assertThat(splits).isNotEmpty();
+ splits.forEach(
+ split -> {
+ Truth.assertThat(split.getKind(0).getName()).isEqualTo(KIND);
+ Truth.assertThat(split.getFilter()).isEqualTo(propertyFilter);
+ });
+ }
+
+ @Test
+ public void testQuerySplitterWithDb() throws DatastoreException {
+ Filter propertyFilter =
+ makeFilter("foo", PropertyFilter.Operator.EQUAL, makeValue("value")).build();
+ Query query =
+ Query.newBuilder()
+ .addKind(KindExpression.newBuilder().setName(KIND).build())
+ .setFilter(propertyFilter)
+ .build();
+
+ PARTITION = PartitionId.newBuilder().setProjectId(PROJECT_ID).setDatabaseId("test-db").build();
+
+ List splits =
+ DatastoreHelper.getQuerySplitter().getSplits(query, PARTITION, 2, DATASTORE);
+
+ Truth.assertThat(splits).isNotEmpty();
+ splits.forEach(
+ split -> {
+ Truth.assertThat(split.getKind(0).getName()).isEqualTo(KIND);
+ Truth.assertThat(split.getFilter()).isEqualTo(propertyFilter);
+ });
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/clirr-ignored-differences.xml b/java-datastore/google-cloud-datastore/clirr-ignored-differences.xml
new file mode 100644
index 000000000000..d1e3a4ff4458
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/clirr-ignored-differences.xml
@@ -0,0 +1,106 @@
+
+
+
+
+
+ com/google/cloud/datastore/ReadOption$QueryAndReadOptions
+ *
+ 8001
+
+
+ com/google/cloud/datastore/execution/request/AggregationQueryRequestProtoPreparer
+ *QueryAndReadOptions*
+ *QueryConfig*
+ 7005
+
+
+
+ com/google/cloud/datastore/DatastoreException
+ 5000
+ com/google/cloud/grpc/BaseGrpcServiceException
+
+
+
+ com/google/cloud/datastore/DatastoreException
+ 5001
+ com/google/cloud/http/BaseHttpServiceException
+
+
+ com/google/cloud/datastore/Datastore
+ void close()
+ 7012
+
+
+ com/google/cloud/datastore/spi/v1/DatastoreRpc
+ void close()
+ 7012
+
+
+ com/google/cloud/datastore/Datastore
+ boolean isClosed()
+ 7012
+
+
+ com/google/cloud/datastore/spi/v1/DatastoreRpc
+ boolean isClosed()
+ 7012
+
+
+ com/google/cloud/datastore/Datastore
+ com.google.cloud.datastore.QueryResults run(com.google.cloud.datastore.Query, com.google.cloud.datastore.models.ExplainOptions, com.google.cloud.datastore.ReadOption[])
+ 7012
+
+
+ com/google/cloud/datastore/Datastore
+ com.google.cloud.datastore.AggregationResults runAggregation(com.google.cloud.datastore.AggregationQuery, com.google.cloud.datastore.models.ExplainOptions, com.google.cloud.datastore.ReadOption[])
+ 7012
+
+
+ com/google/cloud/datastore/DatastoreReader
+ com.google.cloud.datastore.AggregationResults runAggregation(com.google.cloud.datastore.AggregationQuery, com.google.cloud.datastore.models.ExplainOptions)
+ 7012
+
+
+ com/google/cloud/datastore/QueryResults
+ java.util.Optional getExplainMetrics()
+ 7012
+
+
+ com/google/cloud/datastore/Transaction
+ com.google.cloud.datastore.QueryResults run(com.google.cloud.datastore.Query, com.google.cloud.datastore.models.ExplainOptions)
+ 7012
+
+
+
+ com/google/cloud/datastore/execution/AggregationQueryExecutor
+ com.google.cloud.datastore.AggregationResults execute(com.google.cloud.datastore.AggregationQuery, com.google.cloud.datastore.ReadOption[])
+ 7004
+
+
+ com/google/cloud/datastore/execution/AggregationQueryExecutor
+ java.lang.Object execute(com.google.cloud.datastore.Query, com.google.cloud.datastore.ReadOption[])
+ 7004
+
+
+ com/google/cloud/datastore/execution/QueryExecutor
+ java.lang.Object execute(com.google.cloud.datastore.Query, com.google.cloud.datastore.ReadOption[])
+ 7004
+
+
+ com/google/cloud/datastore/RetryAndTraceDatastoreRpcDecorator
+ RetryAndTraceDatastoreRpcDecorator(com.google.cloud.datastore.spi.v1.DatastoreRpc, com.google.cloud.datastore.TraceUtil, com.google.api.gax.retrying.RetrySettings, com.google.cloud.datastore.DatastoreOptions)
+ RetryAndTraceDatastoreRpcDecorator(com.google.cloud.datastore.spi.v1.DatastoreRpc, com.google.cloud.datastore.telemetry.TraceUtil, com.google.api.gax.retrying.RetrySettings, com.google.cloud.datastore.DatastoreOptions)
+ 7005
+
+
+
+
+ com/google/cloud/datastore/TraceUtil
+ 8001
+
+
+ com/google/cloud/datastore/testing/RemoteDatastoreHelper
+ 8001
+
+
+
diff --git a/java-datastore/google-cloud-datastore/pom.xml b/java-datastore/google-cloud-datastore/pom.xml
new file mode 100644
index 000000000000..fe82b404848d
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/pom.xml
@@ -0,0 +1,317 @@
+
+
+ 4.0.0
+ google-cloud-datastore
+ 2.33.2
+ jar
+ Google Cloud Datastore
+ https://github.com/googleapis/java-datastore
+
+ Java idiomatic client for Google Cloud Datastore.
+
+
+ com.google.cloud
+ google-cloud-datastore-parent
+ 2.33.2
+
+
+ google-cloud-datastore
+
+
+
+
+
+ com.google.cloud
+ gapic-libraries-bom
+ 1.61.0
+ pom
+ import
+
+
+
+
+
+ com.google.api.grpc
+ grpc-google-cloud-datastore-v1
+
+
+ com.google.api.grpc
+ grpc-google-cloud-datastore-admin-v1
+
+
+ com.google.cloud
+ google-cloud-core-http
+
+
+ com.google.cloud
+ google-cloud-core-grpc
+
+
+ com.google.api.grpc
+ proto-google-cloud-datastore-v1
+
+
+ com.google.api.grpc
+ proto-google-cloud-datastore-admin-v1
+
+
+ com.google.cloud.datastore
+ datastore-v1-proto-client
+
+
+ com.google.auth
+ google-auth-library-credentials
+
+
+ io.grpc
+ grpc-api
+
+
+ io.grpc
+ grpc-protobuf
+
+
+ io.grpc
+ grpc-stub
+
+
+ com.google.api
+ api-common
+
+
+ org.threeten
+ threetenbp
+
+
+ com.google.protobuf
+ protobuf-java
+
+
+ com.google.api
+ gax
+
+
+ com.google.api
+ gax-grpc
+
+
+ com.google.api
+ gax-httpjson
+
+
+ com.google.guava
+ guava
+
+
+ com.google.cloud
+ google-cloud-core
+
+
+ com.google.api.grpc
+ proto-google-common-protos
+
+
+ com.google.http-client
+ google-http-client
+
+
+ com.google.http-client
+ google-http-client-jackson2
+
+
+ com.google.oauth-client
+ google-oauth-client
+
+
+ com.google.auth
+ google-auth-library-oauth2-http
+
+
+ io.opencensus
+ opencensus-api
+
+
+ com.google.code.findbugs
+ jsr305
+
+
+
+
+ io.opentelemetry
+ opentelemetry-api
+
+
+ io.opentelemetry
+ opentelemetry-context
+
+
+ io.opentelemetry.instrumentation
+ opentelemetry-grpc-1.6
+
+
+
+
+
+ ${project.groupId}
+ google-cloud-core
+ test-jar
+ test
+
+
+ com.google.guava
+ guava-testlib
+ 33.4.0-jre
+ test
+
+
+
+ com.google.api
+ gax
+ testlib
+ test
+
+
+ com.google.api
+ gax-grpc
+ testlib
+ test
+
+
+ com.google.api
+ gax-httpjson
+ testlib
+ test
+
+
+ junit
+ junit
+ test
+
+
+ org.easymock
+ easymock
+ test
+
+
+ com.google.truth
+ truth
+ 1.4.4
+ test
+
+
+ com.google.testparameterinjector
+ test-parameter-injector
+ 1.17
+ test
+
+
+
+ io.opentelemetry
+ opentelemetry-sdk
+ test
+
+
+ io.opentelemetry
+ opentelemetry-sdk-common
+ test
+
+
+ io.opentelemetry
+ opentelemetry-sdk-testing
+ test
+
+
+ io.opentelemetry
+ opentelemetry-sdk-trace
+ test
+
+
+ io.opentelemetry
+ opentelemetry-semconv
+ 1.1.0-alpha
+ test
+
+
+
+
+ com.google.cloud.opentelemetry
+ exporter-trace
+ 0.15.0
+ test
+
+
+ com.google.cloud
+ google-cloud-trace
+ test
+
+
+ com.google.api.grpc
+ proto-google-cloud-trace-v1
+ test
+
+
+
+
+
+
+
+ org.codehaus.mojo
+ flatten-maven-plugin
+
+
+
+
+
+ native
+
+
+ com.google.cloud.datastore.it.ITDatastoreConceptsTest
+
+
+
+ java17
+
+ [17,)
+
+
+
+
+ org.apache.maven.plugins
+ maven-compiler-plugin
+
+ UTF-8
+ true
+
+ -XDcompilePolicy=simple
+ --should-stop=ifError=FLOW
+ -Xplugin:ErrorProne -XepExcludedPaths:.*/generated-sources/.*
+
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
+ -J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
+ -J--add-opens=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
+ -J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED
+
+
+
+
+ com.google.errorprone
+ error_prone_core
+ ${error-prone.version}
+
+
+
+
+
+
+
+
+
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationQuery.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationQuery.java
new file mode 100644
index 000000000000..d54b40f1283b
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationQuery.java
@@ -0,0 +1,187 @@
+/*
+ * Copyright 2026 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
+ *
+ * https://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.datastore;
+
+import static com.google.cloud.datastore.AggregationQuery.Mode.GQL;
+import static com.google.cloud.datastore.AggregationQuery.Mode.STRUCTURED;
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.cloud.datastore.aggregation.Aggregation;
+import com.google.cloud.datastore.aggregation.AggregationBuilder;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * An implementation of a Google Cloud Datastore Query that returns {@link AggregationResults}, It
+ * can be constructed by providing a nested query ({@link StructuredQuery} or {@link GqlQuery}) to
+ * run the aggregations on and a set of {@link Aggregation}.
+ *
+ * {@link StructuredQuery} example:
+ *
+ *
{@code
+ * EntityQuery selectAllQuery = Query.newEntityQueryBuilder()
+ * .setKind("Task")
+ * .build();
+ * AggregationQuery aggregationQuery = Query.newAggregationQueryBuilder()
+ * .addAggregation(count().as("total_count"))
+ * .over(selectAllQuery)
+ * .build();
+ * AggregationResults aggregationResults = datastore.runAggregation(aggregationQuery);
+ * for (AggregationResult aggregationResult : aggregationResults) {
+ * System.out.println(aggregationResult.get("total_count"));
+ * }
+ * }
+ *
+ * {@link GqlQuery} example:
+ *
+ *
{@code
+ * GqlQuery selectAllGqlQuery = Query.newGqlQueryBuilder(
+ * "AGGREGATE COUNT(*) AS total_count, COUNT_UP_TO(100) AS count_upto_100 OVER(SELECT * FROM Task)"
+ * )
+ * .setAllowLiteral(true)
+ * .build();
+ * AggregationQuery aggregationQuery = Query.newAggregationQueryBuilder()
+ * .over(selectAllGqlQuery)
+ * .build();
+ * AggregationResults aggregationResults = datastore.runAggregation(aggregationQuery);
+ * for (AggregationResult aggregationResult : aggregationResults) {
+ * System.out.println(aggregationResult.get("total_count"));
+ * System.out.println(aggregationResult.get("count_upto_100"));
+ * }
+ * }
+ *
+ * @see Datastore
+ * queries
+ */
+public class AggregationQuery extends Query {
+
+ private Set aggregations;
+ private StructuredQuery nestedStructuredQuery;
+ private final Mode mode;
+ private GqlQuery nestedGqlQuery;
+
+ AggregationQuery(
+ String namespace, Set aggregations, StructuredQuery nestedQuery) {
+ super(namespace);
+ checkArgument(
+ !aggregations.isEmpty(),
+ "At least one aggregation is required for an aggregation query to run");
+ this.aggregations = aggregations;
+ this.nestedStructuredQuery = nestedQuery;
+ this.mode = STRUCTURED;
+ }
+
+ AggregationQuery(String namespace, GqlQuery gqlQuery) {
+ super(namespace);
+ this.nestedGqlQuery = gqlQuery;
+ this.mode = GQL;
+ }
+
+ /** Returns the {@link Aggregation}(s) for this Query. */
+ public Set getAggregations() {
+ return aggregations;
+ }
+
+ /**
+ * Returns the underlying {@link StructuredQuery for this Query}. Returns null if created with
+ * {@link GqlQuery}
+ */
+ public StructuredQuery getNestedStructuredQuery() {
+ return nestedStructuredQuery;
+ }
+
+ /**
+ * Returns the underlying {@link GqlQuery for this Query}. Returns null if created with {@link
+ * StructuredQuery}
+ */
+ public GqlQuery getNestedGqlQuery() {
+ return nestedGqlQuery;
+ }
+
+ /** Returns the {@link Mode} for this query. */
+ public Mode getMode() {
+ return mode;
+ }
+
+ public static class Builder {
+
+ private String namespace;
+ private Mode mode;
+ private final Set aggregations;
+ private StructuredQuery nestedStructuredQuery;
+ private GqlQuery nestedGqlQuery;
+
+ public Builder() {
+ this.aggregations = new HashSet<>();
+ }
+
+ public Builder setNamespace(String namespace) {
+ this.namespace = namespace;
+ return this;
+ }
+
+ public Builder addAggregation(AggregationBuilder aggregationBuilder) {
+ this.aggregations.add(aggregationBuilder.build());
+ return this;
+ }
+
+ public Builder addAggregation(Aggregation aggregation) {
+ this.aggregations.add(aggregation);
+ return this;
+ }
+
+ public Builder addAggregations(AggregationBuilder... aggregationBuilders) {
+ for (AggregationBuilder builder : aggregationBuilders) {
+ this.aggregations.add(builder.build());
+ }
+ return this;
+ }
+
+ public Builder addAggregations(Aggregation... aggregations) {
+ this.aggregations.addAll(Arrays.asList(aggregations));
+ return this;
+ }
+
+ public Builder over(StructuredQuery nestedQuery) {
+ this.nestedStructuredQuery = nestedQuery;
+ this.mode = STRUCTURED;
+ return this;
+ }
+
+ public Builder over(GqlQuery nestedQuery) {
+ this.nestedGqlQuery = nestedQuery;
+ this.mode = GQL;
+ return this;
+ }
+
+ public AggregationQuery build() {
+ boolean nestedQueryProvided = nestedGqlQuery != null || nestedStructuredQuery != null;
+ checkArgument(
+ nestedQueryProvided, "Nested query is required for an aggregation query to run");
+
+ if (mode == GQL) {
+ return new AggregationQuery(namespace, nestedGqlQuery);
+ }
+ return new AggregationQuery(namespace, aggregations, nestedStructuredQuery);
+ }
+ }
+
+ public enum Mode {
+ STRUCTURED,
+ GQL,
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationResult.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationResult.java
new file mode 100644
index 000000000000..aa9f1ad8bdc1
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationResult.java
@@ -0,0 +1,132 @@
+/*
+ * Copyright 2026 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
+ *
+ * https://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.datastore;
+
+import com.google.api.core.ObsoleteApi;
+import com.google.common.base.MoreObjects;
+import com.google.common.base.MoreObjects.ToStringHelper;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Objects;
+
+/** Represents a result of an {@link AggregationQuery} query submission. */
+public class AggregationResult {
+
+ private final Map> properties;
+
+ public AggregationResult(Map> properties) {
+ this.properties = properties;
+ }
+
+ /**
+ * Returns a result value for the given alias. {@link #getLong(String)} is preferred over this
+ * method, Use {@link #getLong(String)} wherever possible.
+ *
+ * @param alias A custom alias provided in the query or an autogenerated alias in the form of
+ * 'property_\d'
+ * @return An aggregation result value for the given alias.
+ */
+ @ObsoleteApi("Please use getLong(String) instead, see Github issue #1175 for details.")
+ public Long get(String alias) {
+ return getLong(alias);
+ }
+
+ /**
+ * Returns a result value for the given alias.
+ *
+ * @param alias A custom alias provided in the query or an autogenerated alias in the form of
+ * 'property_\d'
+ * @return An aggregation result value for the given alias.
+ */
+ public Long getLong(String alias) {
+ Value value = properties.get(alias);
+ switch (value.getType()) {
+ case DOUBLE:
+ return ((Double) value.get()).longValue();
+ case LONG:
+ return (Long) value.get();
+ default:
+ throw new RuntimeException(
+ String.format("Unsupported type %s received for alias '%s'.", value.getType(), alias));
+ }
+ }
+
+ /**
+ * Returns a result value for the given alias.
+ *
+ * @param alias A custom alias provided in the query or an autogenerated alias in the form of
+ * 'property_\d'
+ * @return An aggregation result value for the given alias.
+ */
+ public Double getDouble(String alias) {
+ Value value = properties.get(alias);
+ switch (value.getType()) {
+ case LONG:
+ return ((Long) value.get()).doubleValue();
+ case DOUBLE:
+ return (Double) value.get();
+ default:
+ throw new RuntimeException(
+ String.format("Unsupported type %s received for alias '%s'.", value.getType(), alias));
+ }
+ }
+
+ /**
+ * Returns a result value for the given alias.
+ *
+ * @param alias A custom alias provided in the query or an autogenerated alias in the form of
+ * 'property_\d'
+ * @return An aggregation result value as a {@link Number} for the given alias.
+ */
+ public Number getNumber(String alias) {
+ Value value = properties.get(alias);
+ switch (value.getType()) {
+ case LONG:
+ return (Long) value.get();
+ case DOUBLE:
+ return (Double) value.get();
+ default:
+ throw new RuntimeException(
+ String.format("Unsupported type %s received for alias '%s'.", value.getType(), alias));
+ }
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (o == null || getClass() != o.getClass()) {
+ return false;
+ }
+ AggregationResult that = (AggregationResult) o;
+ return properties.equals(that.properties);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(properties);
+ }
+
+ @Override
+ public String toString() {
+ ToStringHelper toStringHelper = MoreObjects.toStringHelper(this);
+ for (Entry> entry : properties.entrySet()) {
+ toStringHelper.add(entry.getKey(), entry.getValue().get());
+ }
+ return toStringHelper.toString();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationResults.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationResults.java
new file mode 100644
index 000000000000..8d722ea86794
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/AggregationResults.java
@@ -0,0 +1,104 @@
+/*
+ * Copyright 2026 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
+ *
+ * https://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.datastore;
+
+import static com.google.api.client.util.Preconditions.checkNotNull;
+
+import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
+import com.google.cloud.Timestamp;
+import com.google.cloud.datastore.models.ExplainMetrics;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * The result of an {@link AggregationQuery} query submission. Contains a List<{@link
+ * AggregationResult}> and readTime {@link Timestamp} in it.
+ *
+ * This can be used to iterate over an underlying List<{@link AggregationResult}> directly.
+ */
+public class AggregationResults implements Iterable {
+
+ private final List aggregationResults;
+ private final Timestamp readTime;
+
+ private final ExplainMetrics explainMetrics;
+
+ @BetaApi
+ public AggregationResults(
+ List aggregationResults,
+ Timestamp readTime,
+ ExplainMetrics explainMetrics) {
+ checkNotNull(aggregationResults, "Aggregation results cannot be null");
+ checkNotNull(readTime, "readTime cannot be null");
+ this.aggregationResults = aggregationResults;
+ this.readTime = readTime;
+ this.explainMetrics = explainMetrics;
+ }
+
+ public AggregationResults(List aggregationResults, Timestamp readTime) {
+ this(aggregationResults, readTime, null);
+ }
+
+ /** Returns {@link Iterator} for underlying List<{@link AggregationResult}>. */
+ @Override
+ public Iterator iterator() {
+ return this.aggregationResults.iterator();
+ }
+
+ public int size() {
+ return this.aggregationResults.size();
+ }
+
+ /**
+ * Returns {@code ExplainMetrics} if {@code ExplainOptions} were enabled. Otherwise, returns null.
+ */
+ @BetaApi
+ public Optional getExplainMetrics() {
+ return Optional.ofNullable(this.explainMetrics);
+ }
+
+ @InternalApi
+ public AggregationResult get(int index) {
+ return this.aggregationResults.get(index);
+ }
+
+ /** Returns read timestamp this result batch was returned from. */
+ public Timestamp getReadTime() {
+ return this.readTime;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (o == null || getClass() != o.getClass()) {
+ return false;
+ }
+ AggregationResults that = (AggregationResults) o;
+ return Objects.equals(aggregationResults, that.aggregationResults)
+ && Objects.equals(readTime, that.readTime)
+ && Objects.equals(explainMetrics, that.explainMetrics);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(aggregationResults, readTime, explainMetrics);
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseDatastoreBatchWriter.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseDatastoreBatchWriter.java
new file mode 100644
index 000000000000..a513d806bcb2
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseDatastoreBatchWriter.java
@@ -0,0 +1,271 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import com.google.common.base.Preconditions;
+import com.google.common.collect.Iterables;
+import com.google.common.collect.Lists;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/** Base class for DatastoreBatchWriter. */
+public abstract class BaseDatastoreBatchWriter implements DatastoreBatchWriter {
+
+ private final String name;
+ private final Map> toAdd = new LinkedHashMap<>();
+ private final List> toAddAutoId = new LinkedList<>();
+ private final Map> toUpdate = new LinkedHashMap<>();
+ private final Map> toPut = new LinkedHashMap<>();
+ private final Set toDelete = new LinkedHashSet<>();
+ private boolean active = true;
+
+ BaseDatastoreBatchWriter(String name) {
+ this.name = name;
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public final void addWithDeferredIdAllocation(FullEntity... entities) {
+ validateActive();
+ for (FullEntity entity : entities) {
+ IncompleteKey key = entity.getKey();
+ Preconditions.checkArgument(key != null, "Entity must have a key");
+ if (key instanceof Key) {
+ addInternal((FullEntity) entity);
+ } else {
+ toAddAutoId.add((FullEntity) entity);
+ }
+ }
+ }
+
+ private void addInternal(FullEntity entity) {
+ Key key = entity.getKey();
+ if (toAdd.containsKey(key) || toUpdate.containsKey(key) || toPut.containsKey(key)) {
+ throw newInvalidRequest(
+ "Entity with the key %s was already added or updated in this %s", entity.getKey(), name);
+ }
+ if (toDelete.remove(key)) {
+ toPut.put(key, entity);
+ } else {
+ toAdd.put(key, entity);
+ }
+ }
+
+ @Override
+ public final Entity add(FullEntity entity) {
+ return DatastoreHelper.add(this, entity);
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public final List add(FullEntity... entities) {
+ validateActive();
+ List incompleteKeys = Lists.newArrayListWithExpectedSize(entities.length);
+ for (FullEntity entity : entities) {
+ IncompleteKey key = entity.getKey();
+ Preconditions.checkArgument(key != null, "Entity must have a key");
+ if (!(key instanceof Key)) {
+ incompleteKeys.add(key);
+ }
+ }
+ Iterator allocated;
+ if (!incompleteKeys.isEmpty()) {
+ IncompleteKey[] toAllocate = Iterables.toArray(incompleteKeys, IncompleteKey.class);
+ allocated = getDatastore().allocateId(toAllocate).iterator();
+ } else {
+ allocated = Collections.emptyIterator();
+ }
+ List answer = Lists.newArrayListWithExpectedSize(entities.length);
+ for (FullEntity entity : entities) {
+ if (entity.getKey() instanceof Key) {
+ addInternal((FullEntity) entity);
+ answer.add(Entity.convert((FullEntity) entity));
+ } else {
+ Entity entityWithAllocatedId = Entity.newBuilder(allocated.next(), entity).build();
+ addInternal(entityWithAllocatedId);
+ answer.add(entityWithAllocatedId);
+ }
+ }
+ return answer;
+ }
+
+ @SafeVarargs
+ @Override
+ public final void update(Entity... entities) {
+ validateActive();
+ for (Entity entity : entities) {
+ Key key = entity.getKey();
+ if (toDelete.contains(key)) {
+ throw newInvalidRequest(
+ "Entity with the key %s was already deleted in this %s", entity.getKey(), name);
+ }
+ if (toAdd.remove(key) != null || toPut.containsKey(key)) {
+ toPut.put(key, entity);
+ } else {
+ toUpdate.put(key, entity);
+ }
+ }
+ }
+
+ private void putInternal(FullEntity entity) {
+ Key key = entity.getKey();
+ toAdd.remove(key);
+ toUpdate.remove(key);
+ toDelete.remove(key);
+ toPut.put(key, entity);
+ }
+
+ @Override
+ public final Entity put(FullEntity entity) {
+ return DatastoreHelper.put(this, entity);
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public final void putWithDeferredIdAllocation(FullEntity... entities) {
+ validateActive();
+ for (FullEntity entity : entities) {
+ IncompleteKey key = entity.getKey();
+ Preconditions.checkArgument(key != null, "Entity must have a key");
+ if (key instanceof Key) {
+ putInternal(Entity.convert((FullEntity) entity));
+ } else {
+ toAddAutoId.add((FullEntity) entity);
+ }
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ @Override
+ public final List put(FullEntity... entities) {
+ validateActive();
+ List incompleteKeys = Lists.newArrayListWithExpectedSize(entities.length);
+ for (FullEntity entity : entities) {
+ IncompleteKey key = entity.getKey();
+ Preconditions.checkArgument(key != null, "Entity must have a key");
+ if (!(key instanceof Key)) {
+ incompleteKeys.add(key);
+ }
+ }
+ Iterator allocated;
+ if (!incompleteKeys.isEmpty()) {
+ IncompleteKey[] toAllocate = Iterables.toArray(incompleteKeys, IncompleteKey.class);
+ allocated = getDatastore().allocateId(toAllocate).iterator();
+ } else {
+ allocated = Collections.emptyIterator();
+ }
+ List answer = Lists.newArrayListWithExpectedSize(entities.length);
+ for (FullEntity entity : entities) {
+ if (entity.getKey() instanceof Key) {
+ putInternal((FullEntity) entity);
+ answer.add(Entity.convert((FullEntity) entity));
+ } else {
+ Entity entityWithAllocatedId = Entity.newBuilder(allocated.next(), entity).build();
+ putInternal(entityWithAllocatedId);
+ answer.add(entityWithAllocatedId);
+ }
+ }
+ return answer;
+ }
+
+ @Override
+ public final void delete(Key... keys) {
+ validateActive();
+ for (Key key : keys) {
+ toAdd.remove(key);
+ toUpdate.remove(key);
+ toPut.remove(key);
+ toDelete.add(key);
+ }
+ }
+
+ @Override
+ public boolean isActive() {
+ return active;
+ }
+
+ protected String getName() {
+ return name;
+ }
+
+ protected Map> toAdd() {
+ return toAdd;
+ }
+
+ protected List> toAddAutoId() {
+ return toAddAutoId;
+ }
+
+ protected Map> toUpdate() {
+ return toUpdate;
+ }
+
+ protected Map> toPut() {
+ return toPut;
+ }
+
+ protected Set toDelete() {
+ return toDelete;
+ }
+
+ protected void deactivate() {
+ active = false;
+ }
+
+ protected void validateActive() {
+ if (!active) {
+ throw newInvalidRequest("%s is no longer active", name);
+ }
+ }
+
+ protected DatastoreException newInvalidRequest(String msg, Object... params) {
+ return DatastoreException.throwInvalidRequest(String.format(msg, params));
+ }
+
+ protected List toMutationPbList() {
+ List mutationsPb = new ArrayList<>();
+ for (FullEntity entity : toAddAutoId()) {
+ mutationsPb.add(
+ com.google.datastore.v1.Mutation.newBuilder().setInsert(entity.toPb()).build());
+ }
+ for (FullEntity entity : toAdd().values()) {
+ mutationsPb.add(
+ com.google.datastore.v1.Mutation.newBuilder().setInsert(entity.toPb()).build());
+ }
+ for (FullEntity entity : toUpdate().values()) {
+ mutationsPb.add(
+ com.google.datastore.v1.Mutation.newBuilder().setUpdate(entity.toPb()).build());
+ }
+ for (FullEntity entity : toPut().values()) {
+ mutationsPb.add(
+ com.google.datastore.v1.Mutation.newBuilder().setUpsert(entity.toPb()).build());
+ }
+ for (Key key : toDelete()) {
+ mutationsPb.add(com.google.datastore.v1.Mutation.newBuilder().setDelete(key.toPb()).build());
+ }
+ return mutationsPb;
+ }
+
+ protected abstract Datastore getDatastore();
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseEntity.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseEntity.java
new file mode 100644
index 000000000000..5bc9229e52ac
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseEntity.java
@@ -0,0 +1,649 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import static com.google.cloud.datastore.BlobValue.of;
+import static com.google.cloud.datastore.BooleanValue.of;
+import static com.google.cloud.datastore.DoubleValue.of;
+import static com.google.cloud.datastore.EntityValue.of;
+import static com.google.cloud.datastore.KeyValue.of;
+import static com.google.cloud.datastore.LatLngValue.of;
+import static com.google.cloud.datastore.ListValue.of;
+import static com.google.cloud.datastore.LongValue.of;
+import static com.google.cloud.datastore.NullValue.of;
+import static com.google.cloud.datastore.StringValue.of;
+import static com.google.cloud.datastore.TimestampValue.of;
+
+import com.google.cloud.Timestamp;
+import com.google.common.base.MoreObjects;
+import com.google.common.collect.ImmutableSortedMap;
+import com.google.common.collect.Maps;
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * A base class for entities (key and properties). An entity is a Google Cloud Datastore persistent
+ * data object. An entity holds one or more properties, represented by a name (as {@link String})
+ * and a value (as {@link com.google.cloud.datastore.Value}), and may be associated with a key. For
+ * a list of possible values see {@link ValueType}.
+ *
+ * @see Google Cloud Datastore
+ * Entities, Properties, and Keys
+ */
+public abstract class BaseEntity implements Serializable {
+
+ private static final long serialVersionUID = -9070588108769487081L;
+ private final ImmutableSortedMap> properties;
+ private final K key;
+
+ public abstract static class Builder> {
+
+ private K key;
+ private final Map> properties = new HashMap<>();
+
+ Builder() {}
+
+ Builder(K key) {
+ setKey(key);
+ }
+
+ Builder(BaseEntity entity) {
+ this(entity.key, entity);
+ }
+
+ Builder(K key, BaseEntity entity) {
+ setKey(key);
+ setProperties(entity.properties);
+ }
+
+ protected K key() {
+ return key;
+ }
+
+ protected Map> setProperties() {
+ return properties;
+ }
+
+ @SuppressWarnings("unchecked")
+ private B self() {
+ return (B) this;
+ }
+
+ @SuppressWarnings("unchecked")
+ B fill(com.google.datastore.v1.Entity entityPb) {
+ Map> copiedProperties = Maps.newHashMap();
+ for (Map.Entry entry :
+ entityPb.getPropertiesMap().entrySet()) {
+ copiedProperties.put(entry.getKey(), Value.fromPb(entry.getValue()));
+ }
+ setProperties(copiedProperties);
+ if (entityPb.hasKey()) {
+ setKey((K) IncompleteKey.fromPb(entityPb.getKey()));
+ }
+ return self();
+ }
+
+ protected B setProperties(Map> properties) {
+ this.properties.putAll(properties);
+ return self();
+ }
+
+ /** Sets the key for the entity. */
+ public B setKey(K key) {
+ this.key = key;
+ return self();
+ }
+
+ /** Clears all the properties. */
+ public B clear() {
+ properties.clear();
+ return self();
+ }
+
+ /** Removes a property with the given {@code name}. */
+ public B remove(String name) {
+ properties.remove(name);
+ return self();
+ }
+
+ /**
+ * Sets a property.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, Value value) {
+ properties.put(name, value);
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link StringValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, String value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link StringValue}.
+ *
+ * @param name name of the property
+ * @param first the first string in the list
+ * @param second the second string in the list
+ * @param others other strings in the list
+ */
+ public B set(String name, String first, String second, String... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (String other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link LongValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, long value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link LongValue}.
+ *
+ * @param name name of the property
+ * @param first the first long in the list
+ * @param second the second long in the list
+ * @param others other longs in the list
+ */
+ public B set(String name, long first, long second, long... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (long other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link DoubleValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, double value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link DoubleValue}.
+ *
+ * @param name name of the property
+ * @param first the first double in the list
+ * @param second the second double in the list
+ * @param others other doubles in the list
+ */
+ public B set(String name, double first, double second, double... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (double other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link BooleanValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, boolean value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link BooleanValue}.
+ *
+ * @param name name of the property
+ * @param first the first boolean in the list
+ * @param second the second boolean in the list
+ * @param others other booleans in the list
+ */
+ public B set(String name, boolean first, boolean second, boolean... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (boolean other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link TimestampValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, Timestamp value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link TimestampValue}.
+ *
+ * @param name name of the property
+ * @param first the first {@link Timestamp} in the list
+ * @param second the second {@link Timestamp} in the list
+ * @param others other {@link Timestamp}s in the list
+ */
+ public B set(String name, Timestamp first, Timestamp second, Timestamp... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (Timestamp other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link LatLng}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, LatLng value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link LatLng}.
+ *
+ * @param name name of the property
+ * @param first the first {@link LatLng} in the list
+ * @param second the second {@link LatLng} in the list
+ * @param others other {@link LatLng}s in the list
+ */
+ public B set(String name, LatLng first, LatLng second, LatLng... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (LatLng other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link KeyValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, Key value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link KeyValue}.
+ *
+ * @param name name of the property
+ * @param first the first {@link Key} in the list
+ * @param second the second {@link Key} in the list
+ * @param others other {@link Key}s in the list
+ */
+ public B set(String name, Key first, Key second, Key... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (Key other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link EntityValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, FullEntity value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link EntityValue}.
+ *
+ * @param name name of the property
+ * @param first the first {@link FullEntity} in the list
+ * @param second the second {@link FullEntity} in the list
+ * @param others other entities in the list
+ */
+ public B set(String name, FullEntity first, FullEntity second, FullEntity... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (FullEntity other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link ListValue}.
+ *
+ * @param name name of the property
+ * @param values list of values associated with the property
+ */
+ public B set(String name, List> values) {
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link ListValue}.
+ *
+ * @param name name of the property
+ * @param first the first value in the list
+ * @param second the second value in the list
+ * @param others other values in the list
+ */
+ public B set(String name, Value first, Value second, Value... others) {
+ properties.put(name, ListValue.newBuilder().addValue(first).addValue(second, others).build());
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@link BlobValue}.
+ *
+ * @param name name of the property
+ * @param value value associated with the property
+ */
+ public B set(String name, Blob value) {
+ properties.put(name, of(value));
+ return self();
+ }
+
+ /**
+ * Sets a list property containing elements of type {@link BlobValue}.
+ *
+ * @param name name of the property
+ * @param first the first {@link Blob} in the list
+ * @param second the second {@link Blob} in the list
+ * @param others other {@link Blob}s in the list
+ */
+ public B set(String name, Blob first, Blob second, Blob... others) {
+ List values = new LinkedList<>();
+ values.add(of(first));
+ values.add(of(second));
+ for (Blob other : others) {
+ values.add(of(other));
+ }
+ properties.put(name, of(values));
+ return self();
+ }
+
+ /**
+ * Sets a property of type {@code NullValue}.
+ *
+ * @param name name of the property
+ */
+ public B setNull(String name) {
+ properties.put(name, of());
+ return self();
+ }
+
+ public abstract BaseEntity build();
+ }
+
+ BaseEntity(Builder builder) {
+ this.key = builder.key;
+ this.properties = ImmutableSortedMap.copyOf(builder.properties);
+ }
+
+ BaseEntity(BaseEntity from) {
+ this.key = from.getKey();
+ this.properties = from.properties;
+ }
+
+ @Override
+ public String toString() {
+ return MoreObjects.toStringHelper(this)
+ .add("key", key)
+ .add("properties", properties)
+ .toString();
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(key, properties);
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+ if (!(obj instanceof BaseEntity)) {
+ return false;
+ }
+ BaseEntity other = (BaseEntity) obj;
+ return Objects.equals(key, other.key) && Objects.equals(properties, other.properties);
+ }
+
+ /** Returns true if entity has a non-null key. */
+ public boolean hasKey() {
+ return key != null;
+ }
+
+ /** Returns the associated key or null if it does not have one. */
+ public K getKey() {
+ return key;
+ }
+
+ /** Returns {@code true} if the entity contains a property with the given {@code name}. */
+ public boolean contains(String name) {
+ return properties.containsKey(name);
+ }
+
+ /**
+ * Returns the {@link Value} for the given property {@code name}.
+ *
+ * @throws DatastoreException if no such property
+ */
+ public > V getValue(String name) {
+ @SuppressWarnings("unchecked")
+ V property = (V) properties.get(name);
+ if (property == null) {
+ throw DatastoreException.throwInvalidRequest("No such property %s", name);
+ }
+ return property;
+ }
+
+ /**
+ * Returns true if property is an instance of NullValue.
+ *
+ * @throws DatastoreException if no such property
+ */
+ public boolean isNull(String name) {
+ return getValue(name) instanceof NullValue;
+ }
+
+ /**
+ * Returns the property value as a string.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a string
+ */
+ @SuppressWarnings("unchecked")
+ public String getString(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as long.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a long
+ */
+ @SuppressWarnings("unchecked")
+ public long getLong(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as a double.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a double
+ */
+ @SuppressWarnings("unchecked")
+ public double getDouble(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as a boolean.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a boolean
+ */
+ @SuppressWarnings("unchecked")
+ public boolean getBoolean(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as a Timestamp.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a Timestamp
+ */
+ @SuppressWarnings("unchecked")
+ public Timestamp getTimestamp(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as a LatLng.
+ *
+ * @throws DatastoreException if no such property.
+ * @throws ClassCastException if value is not a LatLng.
+ */
+ @SuppressWarnings("unchecked")
+ public LatLng getLatLng(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as a Key.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a Key
+ */
+ @SuppressWarnings("unchecked")
+ public Key getKey(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as an entity.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not an entity
+ */
+ @SuppressWarnings("unchecked")
+ public FullEntity getEntity(String name) {
+ return ((Value>) getValue(name)).get();
+ }
+
+ /**
+ * Returns the property value as a list of values.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a list of values
+ */
+ @SuppressWarnings("unchecked")
+ public > List getList(String name) {
+ return (List) getValue(name).get();
+ }
+
+ /**
+ * Returns the property value as a blob.
+ *
+ * @throws DatastoreException if no such property
+ * @throws ClassCastException if value is not a blob
+ */
+ @SuppressWarnings("unchecked")
+ public Blob getBlob(String name) {
+ return ((Value) getValue(name)).get();
+ }
+
+ /** Returns the properties name. */
+ public Set getNames() {
+ return properties.keySet();
+ }
+
+ /** Returns the properties. */
+ public Map> getProperties() {
+ return properties;
+ }
+
+ final com.google.datastore.v1.Entity toPb() {
+ com.google.datastore.v1.Entity.Builder entityPb = com.google.datastore.v1.Entity.newBuilder();
+ for (Map.Entry> entry : properties.entrySet()) {
+ entityPb.putProperties(entry.getKey(), entry.getValue().toPb());
+ }
+ if (key != null) {
+ entityPb.setKey(key.toPb());
+ }
+ return entityPb.build();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseKey.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseKey.java
new file mode 100644
index 000000000000..3658c3f71172
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BaseKey.java
@@ -0,0 +1,217 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import static com.google.cloud.datastore.Validator.validateKind;
+import static com.google.cloud.datastore.Validator.validateNamespace;
+import static com.google.cloud.datastore.Validator.validateProjectId;
+
+import com.google.common.base.MoreObjects;
+import com.google.common.base.Preconditions;
+import com.google.common.collect.ImmutableList;
+import java.io.Serializable;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Objects;
+
+/** Base class for keys. */
+public abstract class BaseKey implements Serializable {
+
+ private static final long serialVersionUID = -5897863400209818325L;
+
+ private final String projectId;
+ private final String namespace;
+ private final String databaseId;
+ private final ImmutableList path;
+
+ /**
+ * Base class for key builders.
+ *
+ * @param the key builder.
+ */
+ public abstract static class Builder> {
+
+ String projectId = "";
+ String namespace = "";
+ String databaseId = "";
+ String kind;
+ final List ancestors;
+
+ private static final int MAX_PATH = 100;
+
+ Builder(String projectId) {
+ this.projectId = validateProjectId(projectId);
+ ancestors = new LinkedList<>();
+ }
+
+ Builder(String projectId, String kind) {
+ this(projectId);
+ this.kind = validateKind(kind);
+ }
+
+ Builder(BaseKey copyFrom) {
+ projectId = copyFrom.getProjectId();
+ namespace = copyFrom.getNamespace();
+ databaseId = copyFrom.getDatabaseId();
+ ancestors = new LinkedList<>(copyFrom.getAncestors());
+ kind = copyFrom.getKind();
+ }
+
+ @SuppressWarnings("unchecked")
+ B self() {
+ return (B) this;
+ }
+
+ /** Adds an ancestor for this key. */
+ public B addAncestor(PathElement ancestor) {
+ Preconditions.checkState(ancestors.size() < MAX_PATH, "path can have at most 100 elements");
+ ancestors.add(ancestor);
+ return self();
+ }
+
+ /** Adds the provided ancestors to the key. */
+ public B addAncestors(PathElement ancestor, PathElement... other) {
+ return addAncestors(ImmutableList.builder().add(ancestor).add(other).build());
+ }
+
+ /** Adds the provided ancestors to the key. */
+ public B addAncestors(Iterable ancestors) {
+ ImmutableList list = ImmutableList.copyOf(ancestors);
+ Preconditions.checkState(
+ this.ancestors.size() + list.size() < MAX_PATH, "path can have at most 100 elements");
+ this.ancestors.addAll(list);
+ return self();
+ }
+
+ /** Sets the kind of the key. */
+ public B setKind(String kind) {
+ this.kind = validateKind(kind);
+ return self();
+ }
+
+ /** Sets the project ID of the key. */
+ public B setProjectId(String projectId) {
+ this.projectId = validateProjectId(projectId);
+ return self();
+ }
+
+ /** Sets the namespace of the key. */
+ public B setNamespace(String namespace) {
+ this.namespace = validateNamespace(namespace);
+ return self();
+ }
+
+ /** Sets the database id of the key. */
+ public B setDatabaseId(String databaseId) {
+ this.databaseId = databaseId;
+ return self();
+ }
+
+ protected abstract BaseKey build();
+ }
+
+ BaseKey(String projectId, String namespace, ImmutableList path) {
+ this(projectId, namespace, "", path);
+ }
+
+ BaseKey(String projectId, String namespace, String databaseId, ImmutableList path) {
+ Preconditions.checkArgument(!path.isEmpty(), "Path must not be empty");
+ this.projectId = projectId;
+ this.namespace = namespace;
+ this.databaseId = databaseId;
+ this.path = path;
+ }
+
+ /** Returns the key's projectId. */
+ public String getProjectId() {
+ return projectId;
+ }
+
+ /** Returns the key's namespace or {@code null} if not provided. */
+ public String getNamespace() {
+ return namespace;
+ }
+
+ public String getDatabaseId() {
+ return databaseId;
+ }
+
+ /** Returns an immutable list with the key's ancestors. */
+ public List getAncestors() {
+ return getPath().subList(0, getPath().size() - 1);
+ }
+
+ /** Returns an immutable list of the key's path (ancestors + self). */
+ List getPath() {
+ return path;
+ }
+
+ PathElement getLeaf() {
+ return getPath().get(getPath().size() - 1);
+ }
+
+ /** Returns the key's kind. */
+ public String getKind() {
+ return getLeaf().getKind();
+ }
+
+ abstract BaseKey getParent();
+
+ @Override
+ public String toString() {
+ return MoreObjects.toStringHelper(this)
+ .add("projectId", projectId)
+ .add("namespace", namespace)
+ .add("databaseId", databaseId)
+ .add("path", path)
+ .toString();
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(getProjectId(), getNamespace(), getDatabaseId(), getPath());
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+ if (!(obj instanceof BaseKey)) {
+ return false;
+ }
+ BaseKey other = (BaseKey) obj;
+ return Objects.equals(getProjectId(), other.getProjectId())
+ && Objects.equals(getNamespace(), other.getNamespace())
+ && Objects.equals(getDatabaseId(), other.getDatabaseId())
+ && Objects.equals(getPath(), other.getPath());
+ }
+
+ com.google.datastore.v1.Key toPb() {
+ com.google.datastore.v1.Key.Builder keyPb = com.google.datastore.v1.Key.newBuilder();
+ com.google.datastore.v1.PartitionId.Builder partitionIdPb =
+ com.google.datastore.v1.PartitionId.newBuilder();
+ partitionIdPb.setProjectId(projectId);
+ partitionIdPb.setDatabaseId(databaseId);
+ partitionIdPb.setNamespaceId(namespace);
+ keyPb.setPartitionId(partitionIdPb.build());
+ for (PathElement pathEntry : path) {
+ keyPb.addPath(pathEntry.toPb());
+ }
+ return keyPb.build();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java
new file mode 100644
index 000000000000..9cd2ef10bcc3
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import com.google.api.core.InternalExtensionOnly;
+import java.util.List;
+import javax.annotation.concurrent.NotThreadSafe;
+
+/**
+ * An interface to represent a batch of write operations. Any write operation that is applied on a
+ * batch will only be sent to the Datastore upon {@link #submit}. A usage example:
+ *
+ * {@code
+ * Entity entity1 = datastore.get(key1);
+ * Batch batch = datastore.newBatch();
+ * Entity entity2 = Entity.newBuilder(key2).set("name", "John").build();
+ * entity1 = Entity.newBuilder(entity1).clear().setNull("bla").build();
+ * Entity entity3 = Entity.newBuilder(key3).set("title", "title").build();
+ * batch.update(entity1);
+ * batch.add(entity2, entity3);
+ * batch.submit();
+ * }
+ *
+ * WARNING: This class maintains an internal state in terms of {@link
+ * java.util.LinkedHashMap} and {@link java.util.LinkedHashSet} which gets updated on every method
+ * call performing CRUD operations to record the mutations. Since {@link java.util.LinkedHashMap} is
+ * not thread safe as per its documentation,
+ * This class too should not be treated as a thread safe class.
+ */
+@NotThreadSafe
+@InternalExtensionOnly
+public interface Batch extends DatastoreBatchWriter {
+
+ interface Response {
+
+ /** Returns a list of keys generated by a batch. */
+ List getGeneratedKeys();
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * If an entity for {@code entity.getKey()} does not exist, {@code entity} is inserted.
+ * Otherwise, {@link #submit()} will throw a {@link DatastoreException} with {@link
+ * DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}.
+ *
+ * @param entity the entity to be added to the datastore
+ * @return The entity that was added
+ * @throws DatastoreException if there was any failure
+ */
+ @Override
+ Entity add(FullEntity entity);
+
+ /**
+ * {@inheritDoc}
+ *
+ *
If none of entities' keys exist, all entities are inserted. If any of entities' keys already
+ * exists, {@link #submit()} will throw a {@link DatastoreException} with {@link
+ * DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. All entities in {@code
+ * entities} whose key did not exist are inserted.
+ *
+ * @param entities entities to be added to the datastore
+ * @return A list of entities that have been added
+ * @throws DatastoreException if there was any failure
+ */
+ @Override
+ List add(FullEntity... entities);
+
+ /**
+ * Submit the batch to the Datastore.
+ *
+ * @return Response of the batch submit operation.
+ * @throws DatastoreException if there was any failure or if batch is no longer active
+ */
+ Response submit();
+
+ /**
+ * Returns the batch associated {@link Datastore}.
+ *
+ * @return The batch associated datastore
+ */
+ Datastore getDatastore();
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BatchImpl.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BatchImpl.java
new file mode 100644
index 000000000000..605d8b18e57e
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BatchImpl.java
@@ -0,0 +1,73 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+
+class BatchImpl extends BaseDatastoreBatchWriter implements Batch {
+
+ private final DatastoreImpl datastore;
+
+ static class ResponseImpl implements Batch.Response {
+
+ private final com.google.datastore.v1.CommitResponse response;
+ private final int numAutoAllocatedIds;
+
+ ResponseImpl(com.google.datastore.v1.CommitResponse response, int numAutoAllocatedIds) {
+ this.response = response;
+ this.numAutoAllocatedIds = numAutoAllocatedIds;
+ }
+
+ @Override
+ public List getGeneratedKeys() {
+ Iterator results =
+ response.getMutationResultsList().iterator();
+ List generated = new ArrayList<>(numAutoAllocatedIds);
+ for (int i = 0; i < numAutoAllocatedIds; i++) {
+ generated.add(Key.fromPb(results.next().getKey()));
+ }
+ return generated;
+ }
+ }
+
+ BatchImpl(DatastoreImpl datastore) {
+ super("batch");
+ this.datastore = datastore;
+ }
+
+ @Override
+ public Batch.Response submit() {
+ validateActive();
+ List mutationsPb = toMutationPbList();
+ com.google.datastore.v1.CommitRequest.Builder requestPb =
+ com.google.datastore.v1.CommitRequest.newBuilder();
+ requestPb.setMode(com.google.datastore.v1.CommitRequest.Mode.NON_TRANSACTIONAL);
+ requestPb.addAllMutations(mutationsPb);
+ requestPb.setProjectId(datastore.getOptions().getProjectId());
+ requestPb.setDatabaseId(datastore.getOptions().getDatabaseId());
+ com.google.datastore.v1.CommitResponse responsePb = datastore.commit(requestPb.build());
+ deactivate();
+ return new ResponseImpl(responsePb, toAddAutoId().size());
+ }
+
+ @Override
+ public Datastore getDatastore() {
+ return datastore;
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Blob.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Blob.java
new file mode 100644
index 000000000000..e2127c3a1de7
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Blob.java
@@ -0,0 +1,141 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.base.MoreObjects;
+import com.google.common.base.MoreObjects.ToStringHelper;
+import com.google.protobuf.ByteString;
+import java.io.BufferedInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.Serializable;
+import java.nio.ByteBuffer;
+
+/**
+ * A Google Cloud Datastore Blob. This class is immutable.
+ *
+ * @see Google Cloud Datastore
+ * Entities, Properties, and Keys
+ */
+public final class Blob implements Serializable {
+
+ private static final long serialVersionUID = 7311366042557240313L;
+
+ private final ByteString byteString;
+
+ Blob(ByteString byteString) {
+ this.byteString = checkNotNull(byteString);
+ }
+
+ @Override
+ public String toString() {
+ ToStringHelper toStringHelper = MoreObjects.toStringHelper(this);
+ StringBuilder stBuilder = new StringBuilder();
+ for (int i = 0; i < Math.min(256, byteString.size()); i++) {
+ stBuilder.append(String.format("%02x", byteString.byteAt(i)));
+ }
+ if (byteString.size() > 256) {
+ stBuilder.append("...");
+ }
+ return toStringHelper.add("bytes", stBuilder.toString()).toString();
+ }
+
+ @Override
+ public int hashCode() {
+ return byteString.hashCode();
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ return obj == this || obj instanceof Blob && byteString.equals(((Blob) obj).byteString);
+ }
+
+ /** Returns the size of this blob. */
+ public int getLength() {
+ return byteString.size();
+ }
+
+ /** Returns a copy as byte array. */
+ public byte[] toByteArray() {
+ return byteString.toByteArray();
+ }
+
+ /** Returns a read-only {@link ByteBuffer} for this blob content. */
+ public ByteBuffer asReadOnlyByteBuffer() {
+ return byteString.asReadOnlyByteBuffer();
+ }
+
+ /** Returns an {@link InputStream} for this blob content. */
+ public InputStream asInputStream() {
+ final ByteBuffer byteBuffer = asReadOnlyByteBuffer();
+ return new InputStream() {
+ @Override
+ public int read() {
+ return !byteBuffer.hasRemaining() ? -1 : byteBuffer.get() & 0xFF;
+ }
+ };
+ }
+
+ /**
+ * Copies bytes into a ByteBuffer.
+ *
+ * @throws java.nio.ReadOnlyBufferException if the target is read-only
+ * @throws java.nio.BufferOverflowException if the target's remaining() space is not large enough
+ * to hold the data
+ */
+ public void copyTo(ByteBuffer target) {
+ byteString.copyTo(target);
+ }
+
+ /**
+ * Copies bytes into a buffer.
+ *
+ * @throws IndexOutOfBoundsException if an offset or size is negative or too large
+ */
+ public void copyTo(byte[] target) {
+ byteString.copyTo(target, 0);
+ }
+
+ ByteString getByteString() {
+ return byteString;
+ }
+
+ public static Blob copyFrom(byte[] bytes) {
+ return new Blob(ByteString.copyFrom(bytes));
+ }
+
+ public static Blob copyFrom(ByteBuffer bytes) {
+ return new Blob(ByteString.copyFrom(bytes));
+ }
+
+ public static Blob copyFrom(InputStream input) throws IOException {
+ BufferedInputStream bufferedInput = new BufferedInputStream(input);
+ ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+ int value;
+ while ((value = bufferedInput.read()) != -1) {
+ bytes.write(value);
+ }
+ return copyFrom(bytes.toByteArray());
+ }
+
+ com.google.datastore.v1.Value toPb() {
+ return com.google.datastore.v1.Value.newBuilder().setBlobValue(byteString).build();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BlobValue.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BlobValue.java
new file mode 100644
index 000000000000..05c61667ec6e
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BlobValue.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import static com.google.datastore.v1.Value.BLOB_VALUE_FIELD_NUMBER;
+
+public final class BlobValue extends Value {
+
+ private static final long serialVersionUID = -5096238337676649540L;
+
+ static final BaseMarshaller MARSHALLER =
+ new BaseMarshaller() {
+
+ private static final long serialVersionUID = -739627441374592171L;
+
+ @Override
+ public int getProtoFieldId() {
+ return BLOB_VALUE_FIELD_NUMBER;
+ }
+
+ @Override
+ public Builder newBuilder(Blob value) {
+ return BlobValue.newBuilder(value);
+ }
+
+ @Override
+ protected Blob getValue(com.google.datastore.v1.Value from) {
+ return new Blob(from.getBlobValue());
+ }
+
+ @Override
+ protected void setValue(BlobValue from, com.google.datastore.v1.Value.Builder to) {
+ to.setBlobValue(from.get().getByteString());
+ }
+ };
+
+ public static final class Builder extends Value.BaseBuilder {
+
+ private Builder() {
+ super(ValueType.BLOB);
+ }
+
+ @Override
+ public BlobValue build() {
+ return new BlobValue(this);
+ }
+ }
+
+ public BlobValue(Blob blob) {
+ this(newBuilder(blob));
+ }
+
+ private BlobValue(Builder builder) {
+ super(builder);
+ }
+
+ @Override
+ public Builder toBuilder() {
+ return new Builder().mergeFrom(this);
+ }
+
+ public static BlobValue of(Blob blob) {
+ return new BlobValue(blob);
+ }
+
+ public static Builder newBuilder(Blob blob) {
+ return new Builder().set(blob);
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BooleanValue.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BooleanValue.java
new file mode 100644
index 000000000000..09f23e9bbcfe
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/BooleanValue.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import static com.google.datastore.v1.Value.BOOLEAN_VALUE_FIELD_NUMBER;
+
+public final class BooleanValue extends Value {
+
+ private static final long serialVersionUID = -6692551696100439451L;
+
+ static final BaseMarshaller MARSHALLER =
+ new BaseMarshaller() {
+
+ private static final long serialVersionUID = 5178009712526977429L;
+
+ @Override
+ public int getProtoFieldId() {
+ return BOOLEAN_VALUE_FIELD_NUMBER;
+ }
+
+ @Override
+ public Builder newBuilder(Boolean value) {
+ return BooleanValue.newBuilder(value);
+ }
+
+ @Override
+ protected Boolean getValue(com.google.datastore.v1.Value from) {
+ return from.getBooleanValue();
+ }
+
+ @Override
+ protected void setValue(BooleanValue from, com.google.datastore.v1.Value.Builder to) {
+ to.setBooleanValue(from.get());
+ }
+ };
+
+ public static final class Builder extends Value.BaseBuilder {
+
+ private Builder() {
+ super(ValueType.BOOLEAN);
+ }
+
+ @Override
+ public BooleanValue build() {
+ return new BooleanValue(this);
+ }
+ }
+
+ public BooleanValue(boolean value) {
+ this(newBuilder(value));
+ }
+
+ private BooleanValue(Builder builder) {
+ super(builder);
+ }
+
+ @Override
+ public Builder toBuilder() {
+ return new Builder().mergeFrom(this);
+ }
+
+ public static BooleanValue of(boolean value) {
+ return new BooleanValue(value);
+ }
+
+ public static Builder newBuilder(boolean value) {
+ return new Builder().set(value);
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Cursor.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Cursor.java
new file mode 100644
index 000000000000..f67e1c264da0
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Cursor.java
@@ -0,0 +1,86 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.base.MoreObjects;
+import com.google.common.base.MoreObjects.ToStringHelper;
+import com.google.common.io.BaseEncoding;
+import com.google.protobuf.ByteString;
+import java.io.Serializable;
+
+/**
+ * A Google Cloud Datastore cursor. The cursor can be used to as a starting point or an ending point
+ * for a {@link Query}
+ */
+public final class Cursor implements Serializable {
+
+ private static final long serialVersionUID = 4688656124180503551L;
+
+ private final ByteString byteString;
+
+ Cursor(ByteString byteString) {
+ this.byteString = byteString;
+ }
+
+ @Override
+ public int hashCode() {
+ return byteString.hashCode();
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ return obj == this || obj instanceof Cursor && byteString.equals(((Cursor) obj).byteString);
+ }
+
+ @Override
+ public String toString() {
+ ToStringHelper toStringHelper = MoreObjects.toStringHelper(this);
+ StringBuilder stBuilder = new StringBuilder();
+ for (int i = 0; i < byteString.size(); i++) {
+ stBuilder.append(String.format("%02x", byteString.byteAt(i)));
+ }
+ return toStringHelper.add("bytes", stBuilder.toString()).toString();
+ }
+
+ ByteString getByteString() {
+ return byteString;
+ }
+
+ /** Returns the cursor in an encoded form that can be used as part of a URL. */
+ public String toUrlSafe() {
+ return BaseEncoding.base64Url().encode(byteString.toByteArray());
+ }
+
+ /** Create a {@code Cursor} given its URL safe encoded form. */
+ public static Cursor fromUrlSafe(String urlSafe) {
+ try {
+ return Cursor.copyFrom(BaseEncoding.base64Url().decode(urlSafe));
+ } catch (IllegalArgumentException e) {
+ throw new IllegalStateException("Unexpected decoding exception", e);
+ }
+ }
+
+ public static Cursor copyFrom(byte[] bytes) {
+ return new Cursor(ByteString.copyFrom(checkNotNull(bytes)));
+ }
+
+ com.google.datastore.v1.Value toPb() {
+ return com.google.datastore.v1.Value.newBuilder().setBlobValue(byteString).build();
+ }
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java
new file mode 100644
index 000000000000..fd1174fe874b
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java
@@ -0,0 +1,577 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import com.google.api.core.BetaApi;
+import com.google.api.core.InternalExtensionOnly;
+import com.google.cloud.Service;
+import com.google.cloud.datastore.models.ExplainOptions;
+import com.google.datastore.v1.TransactionOptions;
+import java.util.Iterator;
+import java.util.List;
+
+/** An interface for Google Cloud Datastore. */
+@InternalExtensionOnly
+public interface Datastore extends Service, DatastoreReaderWriter, AutoCloseable {
+
+ /**
+ * Returns a new Datastore transaction.
+ *
+ * @param options a transaction option indicating the mode of the transaction (read-only or
+ * read-write)
+ * @throws DatastoreException upon failure
+ */
+ Transaction newTransaction(TransactionOptions options);
+
+ /**
+ * Returns a new Datastore transaction.
+ *
+ * @throws DatastoreException upon failure
+ */
+ Transaction newTransaction();
+
+ /**
+ * A callback for running with a transactional {@link
+ * com.google.cloud.datastore.DatastoreReaderWriter}. The associated transaction will be committed
+ * after a successful return from the {@code run} method. Any propagated exception will cause the
+ * transaction to be rolled-back.
+ *
+ * @param the type of the return value
+ */
+ interface TransactionCallable {
+ /**
+ * Callback's invoke method for the TransactionCallable.
+ *
+ * @param readerWriter DatastoreReaderWriter associated with the new transaction
+ * @return T The transaction result
+ * @throws Exception upon failure
+ */
+ T run(DatastoreReaderWriter readerWriter) throws Exception;
+ }
+
+ /**
+ * Invokes the callback's {@link Datastore.TransactionCallable#run} method with a {@link
+ * DatastoreReaderWriter} that is associated with a new transaction. The transaction will be
+ * committed upon successful invocation. Any thrown exception will cause the transaction to
+ * rollback and will be propagated as a {@link DatastoreException} with the original exception as
+ * its root cause.
+ *
+ * Example of running in a transaction.
+ *
+ *
{@code
+ * String callableResult = "my_callable_result";
+ * TransactionCallable callable = new TransactionCallable() {
+ * public String run(DatastoreReaderWriter readerWriter) {
+ * // use readerWriter to run in transaction
+ * return callableResult;
+ * }
+ * };
+ * String result = datastore.runInTransaction(callable);
+ * }
+ *
+ * @param callable the callback to call with a newly created transactional readerWriter
+ * @throws DatastoreException upon failure
+ */
+ T runInTransaction(TransactionCallable callable);
+
+ /**
+ * Invokes the callback's {@link Datastore.TransactionCallable#run} method with a {@link
+ * DatastoreReaderWriter} that is associated with a new transaction. The transaction will be
+ * committed upon successful invocation. Any thrown exception will cause the transaction to
+ * rollback and will be propagated as a {@link DatastoreException} with the original exception as
+ * its root cause. If {@link TransactionOptions} is set to read-write mode, previous transaction
+ * Id in the options will be automatically populated each time a transaction is retried.
+ *
+ * Example of running in a transaction.
+ *
+ *
{@code
+ * String callableResult = "my_callable_result";
+ * TransactionCallable callable = new TransactionCallable() {
+ * public String run(DatastoreReaderWriter readerWriter) {
+ * // use readerWriter to run in transaction
+ * return callableResult;
+ * }
+ * };
+ *
+ * TransactionOptions options = TransactionOptions.newBuilder()
+ * .setReadWrite(TransactionOptions.ReadWrite
+ * .getDefaultInstance())
+ * .build();
+ *
+ * String result = datastore.runInTransaction(callable, options);
+ * }
+ *
+ * @param callable the callback to call with a newly created transactional readerWriter
+ * @param options the Transaction options indicating whether the transaction mode is Read-only or
+ * Read-Write
+ * @throws DatastoreException upon failure
+ */
+ T runInTransaction(TransactionCallable callable, TransactionOptions options);
+
+ /**
+ * Returns a new Batch for processing multiple write operations in one request.
+ *
+ * Example of starting a new batch.
+ *
+ *
{@code
+ * String keyName1 = "my_key_name_1";
+ * String keyName2 = "my_key_name_2";
+ * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+ * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+ * Batch batch = datastore.newBatch();
+ * Entity entity1 = Entity.newBuilder(key1).set("name", "John").build();
+ * Entity entity2 = Entity.newBuilder(key2).set("title", "title").build();
+ * batch.add(entity1);
+ * batch.add(entity2);
+ * batch.submit();
+ * }
+ */
+ Batch newBatch();
+
+ /**
+ * Allocate a unique id for the given key. The returned key will have the same information
+ * (projectId, kind, namespace and ancestors) as the given key and will have a newly assigned id.
+ *
+ * Example of allocating an id.
+ *
+ *
{@code
+ * KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
+ * IncompleteKey incompleteKey = keyFactory.newKey();
+ *
+ * // let cloud datastore automatically assign an id
+ * Key key = datastore.allocateId(incompleteKey);
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ Key allocateId(IncompleteKey key);
+
+ /**
+ * Returns a list of keys using the allocated ids ordered by the input.
+ *
+ * Example of allocating multiple ids in a single batch.
+ *
+ *
{@code
+ * KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
+ * IncompleteKey incompleteKey1 = keyFactory.newKey();
+ * IncompleteKey incompleteKey2 = keyFactory.newKey();
+ *
+ * // let cloud datastore automatically assign the ids
+ * List keys = datastore.allocateId(incompleteKey1, incompleteKey2);
+ * }
+ *
+ * @throws DatastoreException upon failure
+ * @see #allocateId(IncompleteKey)
+ */
+ List allocateId(IncompleteKey... keys);
+
+ /**
+ * Reserve one or more keys, preventing them from being automatically allocated by Datastore.
+ *
+ * Example of reserving multiple ids in a single batch.
+ *
+ *
{@code
+ * KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
+ * Key key1 = keyFactory.newKey(10);
+ * Key key2 = keyFactory.newKey("name");
+ * List keys = datastore.reserveIds(key1, key2);
+ *
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ List reserveIds(Key... keys);
+
+ /**
+ * {@inheritDoc}
+ *
+ * If an entity for {@code entity.getKey()} does not exist, {@code entity} is inserted.
+ * Otherwise, a {@link DatastoreException} is thrown with {@link DatastoreException#getReason()}
+ * equal to {@code "ALREADY_EXISTS"}.
+ *
+ *
Example of adding a single entity.
+ *
+ *
{@code
+ * String keyName = "my_key_name";
+ * Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
+ * Entity.Builder entityBuilder = Entity.newBuilder(key);
+ * entityBuilder.set("propertyName", "value");
+ * Entity entity = entityBuilder.build();
+ * try {
+ * datastore.add(entity);
+ * } catch (DatastoreException ex) {
+ * if ("ALREADY_EXISTS".equals(ex.getReason())) {
+ * // entity.getKey() already exists
+ * }
+ * }
+ * }
+ *
+ * @throws DatastoreException upon failure or if an entity for {@code entity.getKey()} already
+ * exists
+ */
+ @Override
+ Entity add(FullEntity entity);
+
+ /**
+ * {@inheritDoc}
+ *
+ * If none of entities' keys exist, all entities are inserted. If any of entities' keys already
+ * exists the method throws a {@link DatastoreException} with {@link
+ * DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. All entities in {@code
+ * entities} whose key did not exist are inserted. To achieve a transactional behavior, use {@link
+ * Transaction}.
+ *
+ *
Example of adding multiple entities.
+ *
+ *
{@code
+ * String keyName1 = "my_key_name1";
+ * String keyName2 = "my_key_name2";
+ * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+ * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+ * entityBuilder1.set("propertyName", "value1");
+ * Entity entity1 = entityBuilder1.build();
+ *
+ * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+ * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+ * entityBuilder2.set("propertyName", "value2");
+ * Entity entity2 = entityBuilder2.build();
+ *
+ * try {
+ * datastore.add(entity1, entity2);
+ * } catch (DatastoreException ex) {
+ * if ("ALREADY_EXISTS".equals(ex.getReason())) {
+ * // at least one of entity1.getKey() and entity2.getKey() already exists
+ * }
+ * }
+ * }
+ *
+ * @throws DatastoreException upon failure or if any of entities' keys already exists
+ */
+ @Override
+ List add(FullEntity... entities);
+
+ /**
+ * {@inheritDoc}
+ *
+ * Example of updating multiple entities.
+ *
+ *
{@code
+ * String keyName1 = "my_key_name_1";
+ * String keyName2 = "my_key_name_2";
+ * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+ * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+ * entityBuilder1.set("propertyName", "updatedValue1");
+ * Entity entity1 = entityBuilder1.build();
+ *
+ * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+ * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+ * entityBuilder2.set("propertyName", "updatedValue2");
+ * Entity entity2 = entityBuilder2.build();
+ *
+ * datastore.update(entity1, entity2);
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ @Override
+ void update(Entity... entities);
+
+ /**
+ * {@inheritDoc}
+ *
+ * Example of putting a single entity.
+ *
+ *
{@code
+ * String keyName = "my_key_name";
+ * Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
+ * Entity.Builder entityBuilder = Entity.newBuilder(key);
+ * entityBuilder.set("propertyName", "value");
+ * Entity entity = entityBuilder.build();
+ * datastore.put(entity);
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ @Override
+ Entity put(FullEntity entity);
+
+ /**
+ * {@inheritDoc}
+ *
+ * Example of putting multiple entities.
+ *
+ *
{@code
+ * String keyName1 = "my_key_name1";
+ * String keyName2 = "my_key_name2";
+ * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+ * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+ * entityBuilder1.set("propertyName", "value1");
+ * Entity entity1 = entityBuilder1.build();
+ *
+ * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+ * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+ * entityBuilder2.set("propertyName", "value2");
+ * Entity entity2 = entityBuilder2.build();
+ *
+ * datastore.put(entity1, entity2);
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ @Override
+ List put(FullEntity... entities);
+
+ /**
+ * {@inheritDoc}
+ *
+ * Example of deleting multiple entities.
+ *
+ *
{@code
+ * String keyName1 = "my_key_name1";
+ * String keyName2 = "my_key_name2";
+ * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+ * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+ * datastore.delete(key1, key2);
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ @Override
+ void delete(Key... keys);
+
+ /**
+ * Returns a new KeyFactory for this service
+ *
+ * Example of creating a {@code KeyFactory}.
+ *
+ *
{@code
+ * KeyFactory keyFactory = datastore.newKeyFactory();
+ * }
+ */
+ KeyFactory newKeyFactory();
+
+ /**
+ * Returns an {@link Entity} for the given {@link Key} or {@code null} if it doesn't exist. {@link
+ * ReadOption}s can be specified if desired.
+ *
+ * Example of getting an entity.
+ *
+ *
{@code
+ * String keyName = "my_key_name";
+ * Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
+ * Entity entity = datastore.get(key);
+ * // Do something with the entity
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ Entity get(Key key, ReadOption... options);
+
+ /**
+ * Returns an {@link Entity} for each given {@link Key} that exists in the Datastore. The order of
+ * the result is unspecified. Results are loaded lazily, so it is possible to get a {@code
+ * DatastoreException} from the returned {@code Iterator}'s {@link Iterator#hasNext hasNext} or
+ * {@link Iterator#next next} methods. {@link ReadOption}s can be specified if desired.
+ *
+ * Example of getting multiple entity objects.
+ *
+ *
{@code
+ * String firstKeyName = "my_first_key_name";
+ * String secondKeyName = "my_second_key_name";
+ * KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
+ * Key firstKey = keyFactory.newKey(firstKeyName);
+ * Key secondKey = keyFactory.newKey(secondKeyName);
+ * Iterator entitiesIterator = datastore.get(Lists.newArrayList(firstKey, secondKey));
+ * List entities = Lists.newArrayList();
+ * while (entitiesIterator.hasNext()) {
+ * Entity entity = entitiesIterator.next();
+ * // do something with the entity
+ * entities.add(entity);
+ * }
+ * }
+ *
+ * @throws DatastoreException upon failure
+ * @see #get(Key)
+ */
+ Iterator get(Iterable keys, ReadOption... options);
+
+ /**
+ * Returns a list with a value for each given key (ordered by input). {@code null} values are
+ * returned for nonexistent keys. When possible prefer using {@link #get(Key...)} to avoid eagerly
+ * loading the results. {@link ReadOption}s can be specified if desired.
+ *
+ * Example of fetching a list of Entity objects.
+ *
+ *
{@code
+ * String firstKeyName = "my_first_key_name";
+ * String secondKeyName = "my_second_key_name";
+ * KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
+ * Key firstKey = keyFactory.newKey(firstKeyName);
+ * Key secondKey = keyFactory.newKey(secondKeyName);
+ * List entities = datastore.fetch(Lists.newArrayList(firstKey, secondKey));
+ * for (Entity entity : entities) {
+ * // do something with the entity
+ * }
+ * }
+ */
+ List fetch(Iterable keys, ReadOption... options);
+
+ /**
+ * Submits a {@link Query} and returns its result. {@link ReadOption}s can be specified if
+ * desired.
+ *
+ * Example of running a query to find all entities of one kind.
+ *
+ *
{@code
+ * String kind = "my_kind";
+ * StructuredQuery query = Query.newEntityQueryBuilder()
+ * .setKind(kind)
+ * .build();
+ * QueryResults results = datastore.run(query);
+ * List entities = Lists.newArrayList();
+ * while (results.hasNext()) {
+ * Entity result = results.next();
+ * // do something with result
+ * entities.add(result);
+ * }
+ * }
+ *
+ * Example of running a query to find all entities with a matching property value.
+ *
+ *
{@code
+ * String kind = "my_kind";
+ * String property = "my_property";
+ * String value = "my_value";
+ * StructuredQuery query = Query.newEntityQueryBuilder()
+ * .setKind(kind)
+ * .setFilter(PropertyFilter.eq(property, value))
+ * .build();
+ * QueryResults results = datastore.run(query);
+ * List entities = Lists.newArrayList();
+ * while (results.hasNext()) {
+ * Entity result = results.next();
+ * // do something with result
+ * entities.add(result);
+ * }
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ QueryResults run(Query query, ReadOption... options);
+
+ /**
+ * Submits a {@link Query} with specified {@link com.google.cloud.datastore.models.ExplainOptions}
+ * and returns its result. {@link ReadOption}s can be specified if desired.
+ *
+ * Example of running a query to find all entities of one kind.
+ *
+ *
{@code
+ * String kind = "my_kind";
+ * StructuredQuery query = Query.newEntityQueryBuilder()
+ * .setKind(kind)
+ * .build();
+ * QueryResults results = datastore.run(query, ExplainOptions.newBuilder().setAnalyze(true).build());
+ * }
+ *
+ * @throws DatastoreException upon failure
+ */
+ @BetaApi
+ QueryResults run(Query query, ExplainOptions explainOptions, ReadOption... options);
+
+ /**
+ * Submits a {@link AggregationQuery} and returns {@link AggregationResults}. {@link ReadOption}s
+ * can be specified if desired.
+ *
+ * Example of running an {@link AggregationQuery} to find the count of entities of one kind.
+ *
+ *
{@link StructuredQuery} example:
+ *
+ *
{@code
+ * EntityQuery selectAllQuery = Query.newEntityQueryBuilder()
+ * .setKind("Task")
+ * .build();
+ * AggregationQuery aggregationQuery = Query.newAggregationQueryBuilder()
+ * .addAggregation(count().as("total_count"))
+ * .over(selectAllQuery)
+ * .build();
+ * AggregationResults aggregationResults = datastore.runAggregation(aggregationQuery);
+ * for (AggregationResult aggregationResult : aggregationResults) {
+ * System.out.println(aggregationResult.get("total_count"));
+ * }
+ * }
+ *
+ * {@link GqlQuery} example:
+ *
+ *
{@code
+ * GqlQuery selectAllGqlQuery = Query.newGqlQueryBuilder(
+ * "AGGREGATE COUNT(*) AS total_count, COUNT_UP_TO(100) AS count_upto_100 OVER(SELECT * FROM Task)"
+ * )
+ * .setAllowLiteral(true)
+ * .build();
+ * AggregationQuery aggregationQuery = Query.newAggregationQueryBuilder()
+ * .over(selectAllGqlQuery)
+ * .build();
+ * AggregationResults aggregationResults = datastore.runAggregation(aggregationQuery);
+ * for (AggregationResult aggregationResult : aggregationResults) {
+ * System.out.println(aggregationResult.get("total_count"));
+ * System.out.println(aggregationResult.get("count_upto_100"));
+ * }
+ * }
+ *
+ * @throws DatastoreException upon failure
+ * @return {@link AggregationResults}
+ */
+ AggregationResults runAggregation(AggregationQuery query, ReadOption... options);
+
+ /**
+ * Submits a {@link AggregationQuery} with specified {@link
+ * com.google.cloud.datastore.models.ExplainOptions} and returns {@link AggregationResults}.
+ * {@link ReadOption}s can be specified if desired.
+ *
+ * Example of running an {@link AggregationQuery} to find the count of entities of one kind.
+ *
+ *
{@link StructuredQuery} example:
+ *
+ *
{@code
+ * EntityQuery selectAllQuery = Query.newEntityQueryBuilder()
+ * .setKind("Task")
+ * .build();
+ * AggregationQuery aggregationQuery = Query.newAggregationQueryBuilder()
+ * .addAggregation(count().as("total_count"))
+ * .over(selectAllQuery)
+ * .build();
+ * AggregationResults aggregationResults = datastore.runAggregation(aggregationQuery, ExplainOptions.newBuilder().setAnalyze(true).build());
+ * }
+ *
+ * @throws DatastoreException upon failure
+ * @return {@link AggregationResults}
+ */
+ @BetaApi
+ AggregationResults runAggregation(
+ AggregationQuery query, ExplainOptions explainOptions, ReadOption... options);
+
+ /**
+ * Closes the gRPC channels associated with this instance and frees up their resources. This
+ * method blocks until all channels are closed. Once this method is called, this Datastore client
+ * is no longer usable.
+ */
+ @Override
+ void close() throws Exception;
+
+ /** Returns true if this background resource has been shut down. */
+ boolean isClosed();
+}
diff --git a/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java
new file mode 100644
index 000000000000..38ff7b6d04ae
--- /dev/null
+++ b/java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java
@@ -0,0 +1,121 @@
+/*
+ * Copyright 2026 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.datastore;
+
+import com.google.api.core.InternalExtensionOnly;
+import java.util.List;
+import javax.annotation.concurrent.NotThreadSafe;
+
+/**
+ * An interface to represent a batch of write operations. All write operation for a batch writer
+ * will be applied to the Datastore in one RPC call.
+ *
+ * WARNING: This class maintains an internal state in terms of {@link
+ * java.util.LinkedHashMap} and {@link java.util.LinkedHashSet} which gets updated on every method
+ * call performing CRUD operations to record the mutations. Since {@link java.util.LinkedHashMap} is
+ * not thread safe as per its