org.springframework.cloud.gcp.data.datastore.core.DatastoreOperations Maven / Gradle / Ivy
/*
* Copyright 2017-2019 the original author or authors.
*
* 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 org.springframework.cloud.gcp.data.datastore.core;
import java.util.Collection;
import java.util.Map;
import java.util.function.Function;
import com.google.cloud.datastore.BaseEntity;
import com.google.cloud.datastore.Key;
import com.google.cloud.datastore.Query;
import org.springframework.cloud.gcp.data.datastore.core.convert.DatastoreEntityConverter;
import org.springframework.data.domain.Example;
/**
* An interface of operations that can be done with Cloud Datastore.
*
* @author Chengyuan Zhao
* @author Vinicius Carvalho
*
* @since 1.1
*/
public interface DatastoreOperations {
/**
* Get an entity based on a id.
* @param id the id of the entity. If this is actually a
* {@link com.google.cloud.datastore.Key} then it will be used. Otherwise it will be
* attempted to be converted to an integer or string value and it will be assumed to
* be a root key value with the Kind determined by the entityClass. param.
* @param entityClass the type of the entity to get.
* @param the class type of the entity.
* @return the entity that was found with that id.
*/
T findById(Object id, Class entityClass);
/**
* Saves an instance of an object to Cloud Datastore.
* Behaves as update or insert.
* Ancestors can be added only to entries with Key ids.
* @param instance the instance to save.
* @param ancestors ancestors that should be added to the entry
* @param the type of the object to save
* @return the instance that was saved.
*/
T save(T instance, Key... ancestors);
/**
* Saves multiple instances of objects to Cloud Datastore.
* Behaves as update or insert.
* Ancestors can be added only to entries with Key ids.
* @param entities the objects to save.
* @param ancestors ancestors that should be added to each entry
* @param the type of entities to save
* @return the entities that were saved.
*/
Iterable saveAll(Iterable entities, Key... ancestors);
/**
* Delete an entity from Cloud Datastore. Deleting IDs that do not exist in Cloud
* Datastore will result in no operation.
* @param id the ID of the entity to delete. If this is actually a
* {@link com.google.cloud.datastore.Key} then it will be used. Otherwise it will be
* attempted to be converted to an integer or string value and it will be assumed to
* be a root key value with the Kind determined by the entityClass.
* @param entityClass the type of the
* @param ths entity type
*/
void deleteById(Object id, Class entityClass);
/**
* Delete multiple IDs from Cloud Datastore. Deleting IDs that do not exist in Cloud
* Datastore will result in no operation.
* @param ids the IDs to delete. If any of these is actually a
* {@link com.google.cloud.datastore.Key} then it will be used. Otherwise it will be
* attempted to be converted to an integer or string value and it will be assumed to
* be a root key value with the Kind determined by the entityClass.
* @param entityClass the type of the
* @param ths entity type
*/
void deleteAllById(Iterable ids, Class entityClass);
/**
* Delete an entity from Cloud Datastore. Deleting entities that don't exist in Cloud
* Datastore will result in no operation.
* @param entity the entity to delete.
* @param the entity type
*/
void delete(T entity);
/**
* Deletes multiple entities from Cloud Datastore. Deleting entities that don't exist
* in Cloud Datastore will result in no operation.
* @param entities the entities to delete.
* @param the entity type.
*/
void deleteAll(Iterable entities);
/**
* Delete all entities of a given domain type.
* @param entityClass the domain type to delete from Cloud Datastore.
* @return the number of entities that were deleted.
*/
long deleteAll(Class entityClass);
/**
* Count all occurrences of entities of the given domain type.
* @param entityClass the domain type to count.
* @return the number of entities of the given type.
*/
long count(Class entityClass);
/**
* Find all the entities of the given IDs. If an ID is actually a
* {@link com.google.cloud.datastore.Key} then it will be used. Otherwise it will be
* attempted to be converted to an integer or string value and it will be assumed to
* be a root key value with the Kind determined by the entityClass.
* @param ids the IDs to search.
* @param entityClass the domain type of the objects.
* @param the type parameter of the domain type.
* @return the entities that were found.
*/
Iterable findAllById(Iterable ids, Class entityClass);
/**
* Finds objects by using a Cloud Datastore query.
* @param query the query to execute.
* @param entityClass the type of object to retrieve.
* @param the type of object to retrieve.
* @return a list of the objects found. If no keys could be found the list will be
* empty.
*/
Iterable query(Query query, Class entityClass);
/**
* Runs given query and applies given function to each entity in the result.
* @param query the query to run.
* @param entityFunc the function to apply to each found entity or key.
* @param the row type of the query. This type can be either {@code Key} or a
* Cloud Datastore entity.
* @param the type to map each entity or key to.
* @return the mapped entities or keys.
*/
Iterable query(Query query, Function entityFunc);
/**
* Finds Cloud Datastore Keys by using a Cloud Datastore query.
* @param query the query to execute that retrieves only Keys.
* @return the list of keys found.
*/
Iterable queryKeys(Query query);
/**
* Get all the entities of the given domain type.
* @param entityClass the domain type to get.
* @param the type param of the domain type.
* @return the entities that were found.
*/
Iterable findAll(Class entityClass);
/**
* Get all the entities of the given domain type applying limit, offset and sort.
* @param entityClass the domain type to get.
* @param queryOptions query options
* @param the type param of the domain type.
* @return the entities that were found.
*/
Collection findAll(Class entityClass, DatastoreQueryOptions queryOptions);
/**
* Check if the given ID belongs to an entity in Cloud Datastore. If this is actually
* a {@link com.google.cloud.datastore.Key} then it will be used. Otherwise it will be
* attempted to be converted to an integer or string value and it will be assumed to
* be a root key value with the Kind determined by the entityClass.
* @param id the ID to search for.
* @param entityClass the domain type of the entities to search for.
* @param the type param of the domain type.
* @return true if the given ID refers to an existing entity. False otherwise.
*/
boolean existsById(Object id, Class entityClass);
/**
* Performs multiple read and write operations in a single transaction.
* @param operations the function that uses {@link DatastoreOperations}
* to perform operations in a transaction.
* @param the final return type of the operations.
* @return the final result of the transaction.
*/
A performTransaction(Function operations);
/**
* Get a Datastore entity based on a id and convert it to a map.
* @param key the key of the entity
* @param valueType type values should be converted to
* @param the value type of the map
* @return if an entity for a given key exists, returns the map representation of it,
* {@code null} otherwise
*/
Map findByIdAsMap(Key key, Class valueType);
/**
* Save a map as a Datastore entity, using map keys as field names.
* @param key the key for the entity
* @param the value type of the map to write
* @param map a map
*/
void writeMap(Key key, Map map);
/**
* Create a {@link com.google.cloud.datastore.Key} from kind name and id.
* @param kind the Cloud Datastore kind name
* @param id object to be used as id; if it is a Long, the value is used, otherwise it isconverted to String
* @return created key
*/
Key createKey(String kind, Object id);
/**
* Create a {@link com.google.cloud.datastore.Key} from entity class and id value.
* @param aClass the Cloud Datastore entity class
* @param id object to be used as id; if it is a Long, the value is used, otherwise it is converted to String
* @return created key
*/
Key createKey(Class aClass, Object id);
/**
* Create a {@link com.google.cloud.datastore.Key} from id property of an entity object.
* @param entity the Cloud Datastore entity object
* @return key for the given entity
*/
Key getKey(Object entity);
/**
* Run query by example.
* @param the type of probe and resulted entities
* @param example the example
* @param queryOptions the query options
* @return query results, converted to objects of class T
*/
Iterable queryByExample(Example example, DatastoreQueryOptions queryOptions);
/**
* Run key query by example.
* @param the type of probe
* @param example the example
* @param queryOptions the query options
* @return result keys
*/
Iterable keyQueryByExample(Example example, DatastoreQueryOptions queryOptions);
/**
* Get the {@link DatastoreEntityConverter} used by this template.
* @return the converter.
*/
DatastoreEntityConverter getDatastoreEntityConverter();
/**
* Finds objects by using a Cloud Datastore query. If the query is a key-query, then keys are
* returned.
* @param query the query to execute.
* @param entityClass the type of object to retrieve.
* @param the type of object to retrieve.
* @return a list of the objects found. If no keys could be found the list will be
* empty.
*/
DatastoreResultsIterable queryKeysOrEntities(Query query, Class entityClass);
/**
* Runs given query and applies given function to each entity in the result.
* @param query the query to run.
* @param entityFunc the function to apply to each found entity or key.
* @param the row type of the query. This type can be either {@code Key} or a
* Cloud Datastore entity.
* @param the type to map each entity or key to.
* @return the mapped entities or keys.
*/
DatastoreResultsIterable queryIterable(Query query, Function entityFunc);
}