Note: Java 8 has reached end of support on January 31, 2024. Your existing Java 8 applications will continue to run and receive traffic. However, App Engine might block re-deployment of applications that use runtimes after their end of support date. We recommend that you migrate to the latest supported version of Java.

DatastoreService (Google App Engine API for Java)

All Superinterfaces:

BaseDatastoreService
```
public interface DatastoreService
extends BaseDatastoreService
```
The DatastoreService provides synchronous access to a schema-less data storage system. The fundamental unit of data in this system is the Entity, which has an immutable identity (represented by a Key) and zero or more mutable properties. Entity objects can be created, updated, deleted, retrieved by identifier, and queried via a combination of properties.
The DatastoreService can be used transactionally and supports the notion of a "current" transaction. A current transaction is established by calling beginTransaction(). The transaction returned by this method ceases to be current when an attempt is made to commit or rollback or when another call is made to beginTransaction(). A transaction can only be current within the Thread that created it.
The various overloads of put, get, and delete all support transactions. Users of this class have the choice of explicitly passing a (potentially null) Transaction to these methods or relying on the behavior governed by the ImplicitTransactionManagementPolicy. If a user explicitly provides a Transaction it is up to the user to call Transaction.commit() or Transaction.rollback() at the proper time. If a user relies on implicit transaction management and the installed policy creates a transaction, that transaction will be committed (in the case of a success) or rolled back (in the case of a failure) before the operation returns to the user. The methods that manage transactions according to ImplicitTransactionManagementPolicy are: delete(Key...), delete(Iterable), get(Key), get(Iterable), put(Entity), and put(Iterable).
The overload of prepare that takes a Transaction parameter behaves the same as the overloads of put, get, and delete that take a Transaction parameter. However, the overload of prepare that does not take a Transaction parameter, unlike put, get, and delete, does not use an existing Transaction if one is already running and does not consult the ImplicitTransactionManagementPolicy if one is not already running.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class DatastoreService.KeyRangeState
Indicates the state of a KeyRange.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`DatastoreService.KeyRangeState`	`allocateIdRange(KeyRange range)` This method allocates a user-specified contiguous range of unique IDs.
`KeyRange`	`allocateIds(Key parent, java.lang.String kind, long num)` IDs are allocated within a namespace defined by a parent key and a kind.
`KeyRange`	`allocateIds(java.lang.String kind, long num)` IDs are allocated within a namespace defined by a parent key and a kind.
`Transaction`	`beginTransaction()` Equivalent to `beginTransaction(TransactionOptions.Builder.withDefaults())`.
`Transaction`	`beginTransaction(TransactionOptions options)` Begins a transaction against the datastore.
`void`	`delete(java.lang.Iterable<Key> keys)` Equivalent to `delete(Key...)`.
`void`	`delete(Key... keys)` Deletes the `Entity entities` specified by `keys`.
`void`	`delete(Transaction txn, java.lang.Iterable<Key> keys)` Exhibits the same behavior as `delete(Iterable)`, but executes within the provided transaction.
`void`	`delete(Transaction txn, Key... keys)` Exhibits the same behavior as `delete(Key...)`, but executes within the provided transaction.
`java.util.Map<Key,Entity>`	`get(java.lang.Iterable<Key> keys)` Retrieves the set of `Entities` matching `keys`.
`Entity`	`get(Key key)` Retrieves the `Entity` with the specified `Key`.
`java.util.Map<Key,Entity>`	`get(Transaction txn, java.lang.Iterable<Key> keys)` Exhibits the same behavior as `get(Iterable)`, but executes within the provided transaction.
`Entity`	`get(Transaction txn, Key key)` Exhibits the same behavior as `get(Key)`, but executes within the provided transaction.
`DatastoreAttributes`	`getDatastoreAttributes()` Retrieves the current datastore's attributes.
`java.util.Map<Index,Index.IndexState>`	`getIndexes()` Returns the application indexes and their states.
`Key`	`put(Entity entity)` If the specified `Entity` does not yet exist in the data store, create it and assign its `Key`.
`java.util.List<Key>`	`put(java.lang.Iterable<Entity> entities)` Performs a batch `put` of all `entities`.
`Key`	`put(Transaction txn, Entity entity)` Exhibits the same behavior as `put(Entity)`, but executes within the provided transaction.
`java.util.List<Key>`	`put(Transaction txn, java.lang.Iterable<Entity> entities)` Exhibits the same behavior as `put(Iterable)`, but executes within the provided transaction.

Methods inherited from interface com.google.appengine.api.datastore.BaseDatastoreService
getActiveTransactions, getCurrentTransaction, getCurrentTransaction, prepare, prepare

- Method Detail
  - get
```
Entity get(Key key)
    throws EntityNotFoundException
```
    Retrieves the Entity with the specified Key.
    If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the ImplicitTransactionManagementPolicy available on the DatastoreServiceConfig.
    
    Throws:
    
    EntityNotFoundException - If the specified entity could not be found.
    
    java.lang.IllegalArgumentException - If the specified key is invalid.
    
    DatastoreFailureException - If any other datastore error occurs.
  - get
```
Entity get(Transaction txn,
           Key key)
    throws EntityNotFoundException
```
    Exhibits the same behavior as get(Key), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.
    
    Throws:
    
    java.lang.IllegalStateException - If txn is not null and not active.
    
    EntityNotFoundException
  - get
```
java.util.Map<Key,Entity> get(java.lang.Iterable<Key> keys)
```
    Retrieves the set of Entities matching keys. The result Map will only contain Keys for which Entities could be found.
    If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the ImplicitTransactionManagementPolicy available on the DatastoreServiceConfig.
    
    Throws:
    
    java.lang.IllegalArgumentException - If any Key in keys is invalid.
    
    DatastoreFailureException - If any other datastore error occurs.
  - get
```
java.util.Map<Key,Entity> get(Transaction txn,
                              java.lang.Iterable<Key> keys)
```
    Exhibits the same behavior as get(Iterable), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.
    
    Throws:
    
    java.lang.IllegalStateException - If txn is not null and not active.
  - put
```
Key put(Entity entity)
```
    If the specified Entity does not yet exist in the data store, create it and assign its Key. If the specified Entity already exists in the data store, save the new version.
    The Key is returned, and is also returned by future calls to entity.getKey().
    If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the ImplicitTransactionManagementPolicy available on the DatastoreServiceConfig.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the specified entity was incomplete.
    
    java.util.ConcurrentModificationException - If the entity group to which the entity belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - put
```
Key put(Transaction txn,
        Entity entity)
```
    Exhibits the same behavior as put(Entity), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.
    
    Throws:
    
    java.lang.IllegalStateException - If txn is not null and not active.
    
    java.util.ConcurrentModificationException - If the entity group to which the entity belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - put
```
java.util.List<Key> put(java.lang.Iterable<Entity> entities)
```
    Performs a batch put of all entities.
    If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the ImplicitTransactionManagementPolicy available on the DatastoreServiceConfig.
    
    Returns:
    
    The Keys that were assigned to the entities that were put. If the Iterable that was provided as an argument has a stable iteration order the Keys in the List we return are in that same order. If the Iterable that was provided as an argument does not have a stable iteration order the order of the Keys in the List we return is undefined.
    
    Throws:
    
    java.lang.IllegalArgumentException - If any entity is incomplete.
    
    java.util.ConcurrentModificationException - If an entity group to which any provided entity belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - put
```
java.util.List<Key> put(Transaction txn,
                        java.lang.Iterable<Entity> entities)
```
    Exhibits the same behavior as put(Iterable), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.
    
    Returns:
    
    The Keys that were assigned to the entities that were put. If the Iterable that was provided as an argument has a stable iteration order the Keys in the List we return are in that same order. If the Iterable that was provided as an argument does not have a stable iteration order the order of the Keys in the List we return is undefined.
    
    Throws:
    
    java.lang.IllegalStateException - If txn is not null and not active.
    
    java.util.ConcurrentModificationException - If an entity group to which any provided entity belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - delete
```
void delete(Key... keys)
```
    Deletes the Entity entities specified by keys.
    If there is a current transaction, this operation will execute within that transaction. In this case it is up to the caller to commit or rollback. If there is no current transaction, the behavior of this method with respect to transactions will be determined by the ImplicitTransactionManagementPolicy available on the DatastoreServiceConfig.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the specified key was invalid.
    
    java.util.ConcurrentModificationException - If an entity group to which any provided key belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - delete
```
void delete(Transaction txn,
            Key... keys)
```
    Exhibits the same behavior as delete(Key...), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.
    
    Throws:
    
    java.lang.IllegalStateException - If txn is not null and not active.
    
    java.util.ConcurrentModificationException - If an entity group to which any provided key belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - delete
```
void delete(java.lang.Iterable<Key> keys)
```
    Equivalent to delete(Key...).
    
    Throws:
    
    java.util.ConcurrentModificationException - If an entity group to which any provided key belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - delete
```
void delete(Transaction txn,
            java.lang.Iterable<Key> keys)
```
    Exhibits the same behavior as delete(Iterable), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.
    
    Throws:
    
    java.lang.IllegalStateException - If txn is not null and not active.
    
    java.util.ConcurrentModificationException - If an entity group to which any provided key belongs was modified concurrently.
    
    DatastoreFailureException - If any other datastore error occurs.
  - beginTransaction
```
Transaction beginTransaction()
```
    Equivalent to beginTransaction(TransactionOptions.Builder.withDefaults()).
    
    Returns:
    
    the Transaction that was started.
    
    Throws:
    
    DatastoreFailureException - If a datastore error occurs.
    
    See Also:
    
    beginTransaction(TransactionOptions)
  - beginTransaction
```
Transaction beginTransaction(TransactionOptions options)
```
    Begins a transaction against the datastore. Callers are responsible for explicitly calling Transaction.commit() or Transaction.rollback() when they no longer need the Transaction.
    The Transaction returned by this call will be considered the current transaction and will be returned by subsequent, same-thread calls to BaseDatastoreService.getCurrentTransaction() and BaseDatastoreService.getCurrentTransaction(Transaction) until one of the following happens: 1) beginTransaction() is invoked from the same thread. In this case BaseDatastoreService.getCurrentTransaction() and BaseDatastoreService.getCurrentTransaction(Transaction) will return the result of the more recent call to beginTransaction(). 2) Transaction.commit() is invoked on the Transaction returned by this method. Whether or not the commit returns successfully, the Transaction will no longer be the current transaction. 3) Transaction.rollback() ()} is invoked on the Transaction returned by this method. Whether or not the rollback returns successfully, the Transaction will no longer be the current transaction.
    
    Parameters:
    
    options - The options for the new transaction.
    
    Returns:
    
    the Transaction that was started.
    
    Throws:
    
    DatastoreFailureException - If a datastore error occurs.
    
    See Also:
    
    BaseDatastoreService.getCurrentTransaction(), TransactionOptions
  - allocateIds
```
KeyRange allocateIds(java.lang.String kind,
                     long num)
```
    IDs are allocated within a namespace defined by a parent key and a kind. This method allocates a contiguous range of unique IDs of size num within the namespace defined by a null parent key (root entities) and the given kind.
    IDs allocated in this manner may be provided manually to newly created entities. They will not be used by the datastore's automatic ID allocator for root entities of the same kind.
    
    Parameters:
    
    kind - The kind for which the root entity IDs should be allocated.
    
    num - The number of IDs to allocate.
    
    Returns:
    
    A KeyRange of size num.
    
    Throws:
    
    java.lang.IllegalArgumentException - If num is less than 1 or if num is greater than 1 billion.
    
    DatastoreFailureException - If a datastore error occurs.
  - allocateIds
```
KeyRange allocateIds(Key parent,
                     java.lang.String kind,
                     long num)
```
    IDs are allocated within a namespace defined by a parent key and a kind. This method allocates a contiguous range of unique IDs of size num within the namespace defined by the given parent key and the given kind.
    IDs allocated in this manner may be provided manually to newly created entities. They will not be used by the datastore's automatic ID allocator for entities with the same kind and parent.
    
    Parameters:
    
    parent - The key for which the child entity IDs should be allocated. Can be null.
    
    kind - The kind for which the child entity IDs should be allocated.
    
    num - The number of IDs to allocate.
    
    Returns:
    
    A range of IDs of size num that are guaranteed to be unique.
    
    Throws:
    
    java.lang.IllegalArgumentException - If parent is not a complete key, if num is less than 1, or if num is greater than 1 billion.
    
    DatastoreFailureException - If a datastore error occurs.
  - allocateIdRange
```
DatastoreService.KeyRangeState allocateIdRange(KeyRange range)
```
    This method allocates a user-specified contiguous range of unique IDs.
    Once these IDs have been allocated they may be provided manually to newly created entities.
    Since the datastore's automatic ID allocator will never assign a key to a new entity that will cause an existing entity to be overwritten, entities written to the given KeyRange will never be overwritten. However, writing entities with manually assigned keys in this range may overwrite existing entities (or new entities written by a separate request) depending on the DatastoreService.KeyRangeState returned.
    This method should only be used if you have an existing numeric id range that you want to reserve, e.g. bulk loading entities that already have IDs. If you don't care about which IDs you receive, use allocateIds(java.lang.String, long) instead.
    
    Parameters:
    
    range - The key range to allocate.
    
    Returns:
    
    The state of the id range allocated.
    
    Throws:
    
    DatastoreFailureException - If a datastore error occurs.
  - getDatastoreAttributes
```
DatastoreAttributes getDatastoreAttributes()
```
    Retrieves the current datastore's attributes.
    
    Returns:
    
    The attributes of the datastore used to fulfill requests.
    
    Throws:
    
    DatastoreFailureException - If a datastore error occurs.
  - getIndexes
```
java.util.Map<Index,Index.IndexState> getIndexes()
```
    Returns the application indexes and their states.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-02-15 UTC.

DatastoreService (Google App Engine API for Java)

Interface DatastoreService

Nested Class Summary

Method Summary

Methods inherited from interface com.google.appengine.api.datastore.BaseDatastoreService

Method Detail

get

get

get

get

put

put

put

put

delete

delete

delete

delete

beginTransaction

beginTransaction

allocateIds

allocateIds

allocateIdRange

getDatastoreAttributes

getIndexes