Transaction (Google Cloud Datastore 0.5.0 API)

All Superinterfaces:

DatastoreReader, DatastoreReaderWriter, DatastoreWriter
```
public interface Transaction
extends DatastoreReaderWriter
```
A Google cloud datastore transaction. Similar to Batch any write operation that is applied on a transaction will only be sent to the Datastore upon commit(). A call to rollback() will invalidate the transaction and discard the changes. Any read operation that is done by a transaction will be part of it and therefore a commit is guaranteed to fail if an entity was modified outside of the transaction after it was read. Write operation on this transaction will not be reflected by read operation (as the changes are only sent to the Datastore upon commit. A usage example:
```
 Transaction transaction = datastore.newTransaction();
 try {
   Entity entity = transaction.get(key);
   if (!entity.contains("last_name") || entity.isNull("last_name")) {
     String[] name = entity.getString("name").split(" ");
     entity = Entity.newBuilder(entity)
         .remove("name")
         .set("first_name", name[0])
         .set("last_name", name[1])
         .build();
     transaction.update(entity);
     transaction.commit();
   }
 } finally {
   if (transaction.isActive()) {
     transaction.rollback();
   }
 }
  
```
See Also:
Google Cloud Datastore transactions

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface Transaction.Response

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`Transaction.Response`

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`active()` Deprecated.
`List<Entity>`	`add(FullEntity<?>... entities)` Datastore add operation.
`void`	`addWithDeferredIdAllocation(FullEntity<?>... entities)` Datastore add operation.
`Transaction.Response`	`commit()` Commit the transaction.
`Datastore`	`datastore()` Deprecated.
`void`	`delete(Key... keys)` A datastore delete operation.
`List<Entity>`	`fetch(Key... keys)` Returns a list with a value for each given key (ordered by input).
`Iterator<Entity>`	`get(Key... key)` Returns an `Entity` for each given `Key` that exists in the Datastore.
`Entity`	`get(Key key)` Returns an `Entity` for the given `Key` or `null` if it doesn't exist.
`Datastore`	`getDatastore()` Returns the transaction associated `Datastore`.
`boolean`	`isActive()` Returns `true` if the transaction is still active (was not committed or rolledback).
`List<Entity>`	`put(FullEntity<?>... entities)` A Datastore put (a.k.a upsert) operation.
`void`	`putWithDeferredIdAllocation(FullEntity<?>... entities)` Datastore put operation.
`void`	`rollback()` Rollback the transaction.
`<T> QueryResults<T>`	`run(Query<T> query)` Submits a `Query` and returns its result.
`void`	`update(Entity... entities)` A Datastore update operation.

Methods inherited from interface com.google.cloud.datastore.DatastoreWriter
add, put

- Method Detail
  - get
```
Entity get(Key key)
```
    Returns an Entity for the given Key or null if it doesn't exist. The requested entity will be part of this Datastore transaction (so a commit is guaranteed to fail if entity was changed by others after it was seen by this transaction) but any write changes in this transaction will not be reflected by the returned entity.
    Example of getting an entity for a given key.
```
 String keyName = "my_key_name";
 Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
 Entity entity = transaction.get(key);
 transaction.commit();
 // Do something with the entity
 
```
    Specified by:
    
    get in interface DatastoreReader
    
    Throws:
    
    DatastoreException - upon failure or if no longer active
  - get
```
Iterator<Entity> get(Key... key)
```
    Returns an Entity for each given Key that exists in the Datastore. The order of the result is unspecified. Results are loaded lazily, so it is possible to get a DatastoreException from the returned Iterator's hasNext or next methods. The requested entities will be part of this Datastore transaction (so a commit is guaranteed to fail if any of the entities was changed by others after they were seen by this transaction) but any write changes in this transaction will not be reflected by the returned entities.
    Example of getting entities for several keys.
```
 String firstKeyName = "my_first_key_name";
 String secondKeyName = "my_second_key_name";
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
 Key firstKey = keyFactory.newKey(firstKeyName);
 Key secondKey = keyFactory.newKey(secondKeyName);
 Iterator<Entity> entitiesIterator = transaction.get(firstKey, secondKey);
 List<Entity> entities = Lists.newArrayList();
 while (entitiesIterator.hasNext()) {
   Entity entity = entitiesIterator.next();
   // do something with the entity
   entities.add(entity);
 }
 transaction.commit();
 
```
    Specified by:
    
    get in interface DatastoreReader
    
    Throws:
    
    DatastoreException - upon failure or if no longer active
    See Also:
    DatastoreReader.get(Key)
  - fetch
```
List<Entity> fetch(Key... keys)
```
    Returns a list with a value for each given key (ordered by input). null values are returned for nonexistent keys. When possible prefer using DatastoreReader.get(Key...) to avoid eagerly loading the results. The requested entities will be part of this Datastore transaction (so a commit is guaranteed to fail if any of the entities was changed by others after they were seen by this transaction) but any write changes in this transaction will not be reflected by the returned entities.
    Example of fetching a list of entities for several keys.
```
 String firstKeyName = "my_first_key_name";
 String secondKeyName = "my_second_key_name";
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
 Key firstKey = keyFactory.newKey(firstKeyName);
 Key secondKey = keyFactory.newKey(secondKeyName);
 List<Entity> entities = transaction.fetch(firstKey, secondKey);
 for (Entity entity : entities) {
   // do something with the entity
 }
 transaction.commit();
 
```
    Specified by:
    
    fetch in interface DatastoreReader
    
    Throws:
    
    DatastoreException - upon failure or if no longer active
  - run
```
<T> QueryResults<T> run(Query<T> query)
```
    Submits a Query and returns its result. The entities returned by the result of this query will be part of this Datastore transaction (so a commit is guaranteed to fail if any of the entities was changed by others after the query was performed) but any write changes in this transaction will not be reflected by the result.
    Example of running a query to find all entities with an ancestor.
```
 String parentKeyName = "my_parent_key_name";
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("ParentKind");
 Key parentKey = keyFactory.newKey(parentKeyName);
 // Build a query
 Query<Entity> query = Query.newEntityQueryBuilder()
     .setKind("MyKind")
     .setFilter(PropertyFilter.hasAncestor(parentKey))
     .build();
 QueryResults<Entity> results = transaction.run(query);
 List<Entity> entities = Lists.newArrayList();
 while (results.hasNext()) {
   Entity result = results.next();
   // do something with result
   entities.add(result);
 }
 transaction.commit();
 
```
    Specified by:
    
    run in interface DatastoreReader
    
    Throws:
    
    DatastoreException - upon failure or if no longer active
  - commit
```
Transaction.Response commit()
```
    Commit the transaction.
    Example of committing a transaction.
```
 // create an entity
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
 Key key = datastore.allocateId(keyFactory.newKey());
 Entity entity = Entity.newBuilder(key).set("description", "commit()").build();
 
 // add the entity and commit
 try {
   transaction.put(entity);
   transaction.commit();
 } catch (DatastoreException ex) {
   // handle exception
 }
 
```
    Throws:
    
    DatastoreException - if could not commit the transaction or if no longer active
  - rollback
```
void rollback()
```
    Rollback the transaction.
    Example of rolling back a transaction.
```
 // create an entity
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
 Key key = datastore.allocateId(keyFactory.newKey());
 Entity entity = Entity.newBuilder(key).set("description", "rollback()").build();
 
 // add the entity and rollback
 transaction.put(entity);
 transaction.rollback();
 // calling transaction.commit() now would fail
 
```
    Throws:
    
    DatastoreException - if transaction was already committed
  - active
```
@Deprecated
boolean active()
```
    Deprecated.
    Returns true if the transaction is still active (was not committed or rolledback).
    Example of verifying if a transaction is active.
```
 // create an entity
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
 Key key = datastore.allocateId(keyFactory.newKey());
 Entity entity = Entity.newBuilder(key).set("description", "active()").build();
 // calling transaction.active() now would return true
 try {
   // add the entity and commit
   transaction.put(entity);
   transaction.commit();
 } finally {
   // if committing succeeded
   // then transaction.active() will be false
   if (transaction.active()) {
     // otherwise it's true and we need to rollback
     transaction.rollback();
   }
 }
 
```
  - isActive
```
boolean isActive()
```
    Returns true if the transaction is still active (was not committed or rolledback).
    Example of verifying if a transaction is active.
```
 // create an entity
 KeyFactory keyFactory = datastore.newKeyFactory().setKind("MyKind");
 Key key = datastore.allocateId(keyFactory.newKey());
 Entity entity = Entity.newBuilder(key).set("description", "active()").build();
 // calling transaction.active() now would return true
 try {
   // add the entity and commit
   transaction.put(entity);
   transaction.commit();
 } finally {
   // if committing succeeded
   // then transaction.active() will be false
   if (transaction.isActive()) {
     // otherwise it's true and we need to rollback
     transaction.rollback();
   }
 }
 
```
  - datastore
```
@Deprecated
Datastore datastore()
```
    Deprecated.
    
    Returns the transaction associated Datastore.
  - getDatastore
```
Datastore getDatastore()
```
    Returns the transaction associated Datastore.
  - addWithDeferredIdAllocation
```
void addWithDeferredIdAllocation(FullEntity<?>... entities)
```
    Datastore add operation. This method will also allocate id for any entity with an incomplete key. As opposed to DatastoreWriter.add(FullEntity), this method will defer any necessary id allocation to submit time.
    
    Throws:
    
    IllegalArgumentException - if any of the given entities is missing a key
    
    DatastoreException - if a given entity with a complete key was already added to this writer or if not active
  - add
```
List<Entity> add(FullEntity<?>... entities)
```
    Datastore add operation. This method will automatically allocate id for any entity with an incomplete key. For entities with complete keys that were marked for deletion in this writer the operation will be changed to put(com.google.cloud.datastore.FullEntity<?>...).
    
    Specified by:
    
    add in interface DatastoreWriter
    
    Returns:
    a list of Entity ordered by input with the same properties and a key that is either newly allocated or the same one if was already complete
    
    Throws:
    
    DatastoreException - if a given entity with the same complete key was already added to this writer, if writer is not active or if id allocation for an entity with an incomplete key failed.
    See Also:
    DatastoreWriter.add(FullEntity)
  - update
```
void update(Entity... entities)
```
    A Datastore update operation. The operation will fail if an entity with the same key does not already exist. This operation will be converted to put(com.google.cloud.datastore.FullEntity<?>...) operation for entities that were already added or put in this writer.
    
    Specified by:
    
    update in interface DatastoreWriter
    
    Throws:
    
    DatastoreException - if an entity is marked for deletion in this writer or if not active
  - delete
```
void delete(Key... keys)
```
    A datastore delete operation. It is OK request a deletion of a non-existing entity. This operation will also remove from this batch any prior writes for entities with the same keys.
    
    Specified by:
    
    delete in interface DatastoreWriter
    
    Throws:
    
    DatastoreException - if not active
  - putWithDeferredIdAllocation
```
void putWithDeferredIdAllocation(FullEntity<?>... entities)
```
    Datastore put operation. This method will also allocate id for any entity with an incomplete key. As opposed to put(FullEntity[]), this method will defer any necessary id allocation to submit time.
    
    Throws:
    
    IllegalArgumentException - if any of the given entities is missing a key
    
    DatastoreException - if not active
  - put
```
List<Entity> put(FullEntity<?>... entities)
```
    A Datastore put (a.k.a upsert) operation. This method will automatically allocate id for any entity with an incomplete key. This operation will also remove from this writer any prior writes for the same entities.
    
    Specified by:
    
    put in interface DatastoreWriter
    
    Returns:
    a list of updated or inserted Entity, ordered by input. Returned keys are either newly allocated or the same one if was already complete.
    
    Throws:
    
    DatastoreException - if not active

Interface Transaction

Nested Class Summary

Method Summary

Methods inherited from interface com.google.cloud.datastore.DatastoreWriter

Method Detail

get

get

fetch

run

commit

rollback

active

isActive

datastore

getDatastore

addWithDeferredIdAllocation

add

update

delete

putWithDeferredIdAllocation

put