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 of 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()