com.google.appengine.api.datastore
Interface DatastoreService

public interface DatastoreService

The DatastoreService provides 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.

Method Summary

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() 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.
java.util.Collection<Transaction>	getActiveTransactions()
Transaction	getCurrentTransaction() Returns the current transaction for this thread, or throws an exception if there is no current transaction.
Transaction	getCurrentTransaction(Transaction returnedIfNoTxn) Returns the current transaction for this thread, or returns the parameter if there is no current transaction.
PreparedQuery	prepare(Query query) Prepares a query for execution.
PreparedQuery	prepare(Transaction txn, Query query) Exhibits the same behavior as prepare(Query), but executes within the provided transaction.
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.

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 DatastoreConfig.

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 DatastoreConfig.

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 DatastoreConfig.

Throws:

java.lang.IllegalArgumentException - If the specified entity was incomplete.

java.util.ConcurrentModificationException - If this entity was modified concurrently in another transaction.

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.

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 DatastoreConfig.

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 any entity was modified concurrently in another transaction.

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

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 DatastoreConfig.

Throws:

java.lang.IllegalArgumentException - If the specified key was invalid.

java.util.ConcurrentModificationException - If this entity was modified concurrently modified in another transaction.

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

delete

void delete(java.lang.Iterable<Key> keys)

Equivalent to delete(Key...).

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

prepare

PreparedQuery prepare(Query query)

Prepares a query for execution.

This method returns a PreparedQuery which can be used to execute and retrieve results from the datastore for query. This operation will not execute in a transaction even if there is a current transaction and it is an ancestor query. This operation also ignores the ImplicitTransactionManagementPolicy. If you are preparing an ancestory query and you want it to execute in a transaction, use prepare(Transaction, Query).

Parameters:

query - a not null Query.

Returns:

a not null PreparedQuery.

prepare

PreparedQuery prepare(Transaction txn,
                      Query query)

Exhibits the same behavior as prepare(Query), but executes within the provided transaction. It is up to the caller to commit or rollback. Transaction can be null.

Throws:

java.lang.IllegalArgumentException - If txn is not null and query is not an ancestor query

java.lang.IllegalStateException - If txn is not null and the txn is not active

beginTransaction

Transaction beginTransaction()

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 getCurrentTransaction() and getCurrentTransaction(Transaction) until one of the following happens: 1) beginTransaction() is invoked from the same thread. In this case getCurrentTransaction() and 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.

Returns:

the Transaction that was started.

Throws:

DatastoreFailureException - If a datastore error occurs.

See Also:

getCurrentTransaction()

getCurrentTransaction

Transaction getCurrentTransaction()

Returns the current transaction for this thread, or throws an exception if there is no current transaction. The current transaction is defined as the result of the most recent, same-thread invocation of beginTransaction() that has not been committed or rolled back. Use this method for when you expect there to be a current transaction and consider it an error if there isn't.

Returns:

The current transaction.

Throws:

java.util.NoSuchElementException - If there is no current transaction.

getCurrentTransaction

Transaction getCurrentTransaction(Transaction returnedIfNoTxn)

Returns the current transaction for this thread, or returns the parameter if there is no current transaction. You can use null or provide your own object to represent null. See getCurrentTransaction() for a definition of "current transaction." Use this method when you're not sure if there is a current transaction.

Parameters:

returnedIfNoTxn - The return value of this method if there is no current transaction. Can be null.

Returns:

The current transaction, or the parameter that was passed in if there is no current transaction.

getActiveTransactions

java.util.Collection<Transaction> getActiveTransactions()

Returns:

All Transactions started by this thread upon which no attempt to commit or rollback has been made.

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.

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.

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.

Parameters:

parent - The kind 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.