public interface DatastoreService extends BaseDatastoreService
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.
Modifier and Type | Interface and Description |
---|---|
static class |
DatastoreService.KeyRangeState
Indicates the state of a
KeyRange . |
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. |
getActiveTransactions, getCurrentTransaction, getCurrentTransaction, prepare, prepare
Entity get(Key key) throws EntityNotFoundException
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
.
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.Entity get(Transaction txn, Key key) throws EntityNotFoundException
get(Key)
, but executes within the provided transaction.
It is up to the caller to commit or rollback. Transaction can be null.java.lang.IllegalStateException
- If txn
is not null and not active.EntityNotFoundException
java.util.Map<Key,Entity> get(java.lang.Iterable<Key> keys)
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
.
java.lang.IllegalArgumentException
- If any Key
in keys is invalid.DatastoreFailureException
- If any other datastore error occurs.java.util.Map<Key,Entity> get(Transaction txn, java.lang.Iterable<Key> keys)
get(Iterable)
, but executes within the provided
transaction. It is up to the caller to commit or rollback. Transaction can be null.java.lang.IllegalStateException
- If txn
is not null and not active.Key put(Entity entity)
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
.
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.Key put(Transaction txn, Entity entity)
put(Entity)
, but executes within the provided
transaction. It is up to the caller to commit or rollback. Transaction can be null.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.java.util.List<Key> put(java.lang.Iterable<Entity> entities)
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
.
Key
s that were assigned to the entities that were put. If the Iterable
that was provided as an argument has a stable iteration order the Key
s 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 Key
s in the List
we return is undefined.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.java.util.List<Key> put(Transaction txn, java.lang.Iterable<Entity> entities)
put(Iterable)
, but executes within the provided
transaction. It is up to the caller to commit or rollback. Transaction can be null.Key
s that were assigned to the entities that were put. If the Iterable
that was provided as an argument has a stable iteration order the Key
s 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 Key
s in the List
we return is undefined.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.void delete(Key... keys)
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
.
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.void delete(Transaction txn, Key... keys)
delete(Key...)
, but executes within the provided
transaction. It is up to the caller to commit or rollback. Transaction can be null.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.void delete(java.lang.Iterable<Key> keys)
delete(Key...)
.java.util.ConcurrentModificationException
- If an entity group to which any provided key belongs
was modified concurrently.DatastoreFailureException
- If any other datastore error occurs.void delete(Transaction txn, java.lang.Iterable<Key> keys)
delete(Iterable)
, but executes within the provided
transaction. It is up to the caller to commit or rollback. Transaction can be null.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.Transaction beginTransaction()
beginTransaction(TransactionOptions.Builder.withDefaults())
.Transaction
that was started.DatastoreFailureException
- If a datastore error occurs.beginTransaction(TransactionOptions)
Transaction beginTransaction(TransactionOptions options)
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.
options
- The options for the new transaction.Transaction
that was started.DatastoreFailureException
- If a datastore error occurs.BaseDatastoreService.getCurrentTransaction()
,
TransactionOptions
KeyRange allocateIds(java.lang.String kind, long num)
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.
kind
- The kind for which the root entity IDs should be allocated.num
- The number of IDs to allocate.KeyRange
of size num
.java.lang.IllegalArgumentException
- If num
is less than 1 or if num
is greater
than 1 billion.DatastoreFailureException
- If a datastore error occurs.KeyRange allocateIds(Key parent, java.lang.String kind, long num)
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.
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.num
that are guaranteed to be unique.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.DatastoreService.KeyRangeState allocateIdRange(KeyRange range)
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.
range
- The key range to allocate.DatastoreFailureException
- If a datastore error occurs.DatastoreAttributes getDatastoreAttributes()
DatastoreFailureException
- If a datastore error occurs.java.util.Map<Index,Index.IndexState> getIndexes()