Transazioni

Questa API è supportata per runtime di prima generazione e può essere utilizzata quando eseguire l'upgrade ai runtime di seconda generazione corrispondenti. Se esegui l'aggiornamento al runtime App Engine Java 11/17, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

Datastore supporta le transazioni. Una transazione è un'operazione o un insieme di operazioni atomiche: o si verificano tutte le operazioni nella transazione o non si verifica nessuna. Un'applicazione può eseguire più operazioni e calcoli in una singola transazione.

Utilizzo delle transazioni

Una transazione è un insieme di operazioni di Datastore su una o più entità. Ogni transazione è garantita come atomica, il che significa che le transazioni non vengono mai applicate parzialmente. Vengono applicate tutte le operazioni nella transazione o nessuna di esse. Le transazioni hanno una durata massima di 60 secondi con un periodo di scadenza di inattività di 10 secondi dopo 30 secondi.

Un'operazione potrebbe non riuscire quando:

• Sono state tentate troppe modifiche simultanee sullo stesso gruppo di entità.
• La transazione supera un limite di risorse.
• Datastore rileva un errore interno.

In tutti questi casi, l'API Datastore solleva un'eccezione.

Nota: se l'applicazione riceve un'eccezione durante l'commit di una transazione, non sempre significa che la transazione non è riuscita. Puoi ricevere eccezioni DatastoreTimeoutException o DatastoreFailureException nei casi in cui le transazioni sono state committate e alla fine verranno applicate correttamente. Se possibile, rendi le transazioni di Datastore idempotenti in modo che, se ripeti una transazione, il risultato finale sia lo stesso.

Le transazioni sono una funzionalità facoltativa di Datastore. Non è obbligatorio utilizzare le transazioni per eseguire operazioni di Datastore.

Ecco un esempio di aggiornamento del campo denominato vacationDays in un'entità di tipo Employee denominata Joe:

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
Transaction txn = datastore.beginTransaction();
try {
  Key employeeKey = KeyFactory.createKey("Employee", "Joe");
  Entity employee = datastore.get(employeeKey);
  employee.setProperty("vacationDays", 10);

  datastore.put(txn, employee);

  txn.commit();
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Tieni presente che, per mantenere i nostri esempi più concisi, a volte omettiamo il blocco finally che esegue un rollback se la transazione è ancora attiva. Nel codice di produzione è importante assicurarsi che ogni transazione sia stata eseguita esplicitamente o sia stato eseguito il rollback.

Gruppi di entità

Ogni entità appartiene a un gruppo di entità, un insieme di una o più entità che possono essere manipolate in una singola transazione. Le relazioni dei gruppi di entità indicano ad App Engine di memorizzare più entità nella stessa parte della rete distribuita. Una transazione configura le operazioni di Datastore per un gruppo di entità e tutte le operazioni vengono applicate come gruppo o non vengono applicate affatto se la transazione non va a buon fine.

Quando l'applicazione crea un'entità, può assegnarne un'altra come principale della nuova entità. L'assegnazione di un'entità principale a una nuova entità la inserisce nello stesso gruppo dell'entità padre.

Un'entità senza un'entità principale è un'entità principale. Un'entità che è un'entità principale per un'altra può avere anche un'entità principale. Una catena di entità principali da un'entità fino alla radice è il percorso per l'entità e i membri del percorso sono i antenati dell'entità. L'entità principale di un'entità viene definita al momento della sua creazione e non può essere modificata in un secondo momento.

Ogni entità con una determinata entità base come predecessore fa parte dello stesso gruppo di entità. Tutte le entità di un gruppo vengono archiviate nello stesso nodo Datastore. Una singola transazione può modificare più entità in un unico gruppo o aggiungere nuove entità al gruppo impostando come entità principale una entità esistente nel gruppo. Il seguente snippet di codice mostra le transazioni su diversi tipi di entità:

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
Entity person = new Entity("Person", "tom");
datastore.put(person);

// Transactions on root entities
Transaction txn = datastore.beginTransaction();

Entity tom = datastore.get(person.getKey());
tom.setProperty("age", 40);
datastore.put(txn, tom);
txn.commit();

// Transactions on child entities
txn = datastore.beginTransaction();
tom = datastore.get(person.getKey());
Entity photo = new Entity("Photo", tom.getKey());

// Create a Photo that is a child of the Person entity named "tom"
photo.setProperty("photoUrl", "http://domain.com/path/to/photo.jpg");
datastore.put(txn, photo);
txn.commit();

// Transactions on entities in different entity groups
txn = datastore.beginTransaction();
tom = datastore.get(person.getKey());
Entity photoNotAChild = new Entity("Photo");
photoNotAChild.setProperty("photoUrl", "http://domain.com/path/to/photo.jpg");
datastore.put(txn, photoNotAChild);

// Throws IllegalArgumentException because the Person entity
// and the Photo entity belong to different entity groups.
txn.commit();

Creazione di un'entità in un gruppo di entità specifico

Quando l'applicazione crea una nuova entità, puoi assegnarla a un gruppo di entità fornendo la chiave di un'altra entità. L'esempio seguente crea la chiave di un'entità MessageBoard, quindi la utilizza per creare e mantenere una entità Message che si trova nello stesso gruppo di entità di MessageBoard:

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

String messageTitle = "Some Title";
String messageText = "Some message.";
Date postDate = new Date();

Key messageBoardKey = KeyFactory.createKey("MessageBoard", boardName);

Entity message = new Entity("Message", messageBoardKey);
message.setProperty("message_title", messageTitle);
message.setProperty("message_text", messageText);
message.setProperty("post_date", postDate);

Transaction txn = datastore.beginTransaction();
datastore.put(txn, message);

txn.commit();

Utilizzo di transazioni tra gruppi

Le transazioni tra gruppi (chiamate anche transazioni XG) operano su più gruppi di entità e si comportano come le transazioni a gruppo singolo descritte sopra, tranne per il fatto che le transazioni tra gruppi non falliscono se il codice tenta di aggiornare le entità di più di un gruppo di entità.

L'utilizzo di una transazione tra gruppi è simile all'utilizzo di una transazione singola, tranne per il fatto che devi specificare che vuoi che la transazione sia tra gruppi quando la avvii, utilizzando TransactionOptions:

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
TransactionOptions options = TransactionOptions.Builder.withXG(true);
Transaction txn = datastore.beginTransaction(options);

Entity a = new Entity("A");
a.setProperty("a", 22);
datastore.put(txn, a);

Entity b = new Entity("B");
b.setProperty("b", 11);
datastore.put(txn, b);

txn.commit();

Cosa si può fare in una transazione

Datastore impone limitazioni a ciò che è possibile fare all'interno di una singola transazione.

Tutte le operazioni del datastore in una transazione devono essere eseguite su entità nello stesso gruppo di entità se la transazione è di un singolo gruppo o su entità in un massimo di venticinque gruppi di entità se la transazione è tra gruppi. Sono incluse le query per le entità in base all'antenato, il recupero delle entità in base alla chiave, l'aggiornamento e l'eliminazione delle entità. Tieni presente che ogni entità base appartiene a un gruppo di entità distinto, pertanto una singola transazione non può creare o operare su più di un&#entità base principale, a meno che non si tratti di una transazione tra gruppi.

Quando due o più transazioni tentano contemporaneamente di modificare entità in uno o più gruppi di entità comuni, solo la prima transazione che esegue il commit delle modifiche può avere esito positivo; tutte le altre non andranno a buon fine al momento del commit. A causa di questo design, l'utilizzo dei gruppi di entità limita il numero di scritture simultanee che puoi eseguire su qualsiasi entità dei gruppi. Quando inizia una transazione, Datastore utilizza il controllo della concorrenza ottimistico controllando l'ora dell'ultimo aggiornamento dei gruppi di entità utilizzati nella transazione. Al momento dell'commit di una transazione per i gruppi di entità, Datastore controlla di nuovo l'ora dell'ultimo aggiornamento dei gruppi di entità utilizzati nella transazione. Se è stato modificato dal controllo iniziale, viene lanciata un'eccezione.

Un'app può eseguire una query durante una transazione, ma solo se include un filtro di antenato. Un'app può anche recuperare le entità Datastore per chiave durante una transazione. Puoi preparare le chiavi prima della transazione oppure puoi crearle all'interno della transazione con nomi o ID chiave.

Isolamento e coerenza

Al di fuori delle transazioni, il livello di isolamento di Datastore è più simile alla lettura confermata. All'interno delle transazioni viene applicato l'isolamento serializzabile. Ciò significa che un'altra transazione non può modificare contemporaneamente i dati letti o modificati da questa transazione.

In una transazione, tutte le letture riflettono lo stato corrente e coerente di Datastore al momento dell'inizio della transazione. Le query e i get all'interno di una transazione hanno la garanzia di vedere un singolo snapshot coerente di Datastore dall'inizio della transazione. Le entità e le righe di indice nel gruppo di entità della transazione sono completamente aggiornate in modo che le query restituiscano l'insieme completo e corretto di entità di risultato, senza i falsi positivi o i falsi negativi che possono verificarsi nelle query al di fuori delle transazioni.

Questa vista istantanea coerente si estende anche alle letture dopo le scritture all'interno delle transazioni. A differenza della maggior parte dei database, le query e i get all'interno di una transazione Datastore non vedono i risultati delle scritture precedenti all'interno della transazione. Nello specifico, se un'entità viene modificata o eliminata all'interno di una transazione, una query o un get restituisce la versione originale dell'entità dall'inizio della transazione o nessuna entità se l'entità non esisteva.

Utilizzi per le transazioni

Questo esempio mostra un utilizzo delle transazioni: l'aggiornamento di un'entità con un nuovo valore della proprietà rispetto al valore corrente. Poiché l'API Datastore non riprova le transazioni, possiamo aggiungere la logica per la ripetizione della transazione nel caso in cui un'altra richiesta aggiorni lo stesso MessageBoard o uno dei suoi Messages contemporaneamente.

int retries = 3;
while (true) {
  Transaction txn = datastore.beginTransaction();
  try {
    Key boardKey = KeyFactory.createKey("MessageBoard", boardName);
    Entity messageBoard = datastore.get(boardKey);

    long count = (Long) messageBoard.getProperty("count");
    ++count;
    messageBoard.setProperty("count", count);
    datastore.put(txn, messageBoard);

    txn.commit();
    break;
  } catch (ConcurrentModificationException e) {
    if (retries == 0) {
      throw e;
    }
    // Allow retry to occur
    --retries;
  } finally {
    if (txn.isActive()) {
      txn.rollback();
    }
  }
}

Avviso: l'esempio riportato sopra mostra l'incremento di un contatore tramite transazioni solo per semplicità. Se la tua app ha contatori aggiornati frequentemente, non devi incrementarli in base alle transazioni o anche all'interno di una singola entità. Una best practice per lavorare con i contatori è suddividerli in più parti, sceglierne una a caso quando devi incrementare il contatore e sommare le parti per ottenere il conteggio totale.

È necessaria una transazione perché il valore potrebbe essere aggiornato da un altro utente dopo che questo codice ha recuperato l'oggetto, ma prima che lo salvi. Senza una transazione, la richiesta dell'utente utilizza il valore count prima dell'aggiornamento dell'altro utente e il salvataggio sovrascrive il nuovo valore. Con una transazione, l'applicazione viene informata dell'aggiornamento dell'altro utente. Se l'entità viene aggiornata durante la transazione, la transazione non va a buon fine con un ConcurrentModificationException. L'applicazione può ripetere la transazione per utilizzare i nuovi dati.

Nota: in casi molto rari, la transazione viene eseguita completamente anche se una transazione restituisce un'eccezione di timeout o di errore interno. Per questo motivo, è meglio eseguire transazioni idempotenti, se possibile.

Un altro utilizzo comune delle transazioni è recuperare un'entità con una chiave denominata o crearla se non esiste ancora:

Transaction txn = datastore.beginTransaction();
Entity messageBoard;
Key boardKey;
try {
  boardKey = KeyFactory.createKey("MessageBoard", boardName);
  messageBoard = datastore.get(boardKey);
} catch (EntityNotFoundException e) {
  messageBoard = new Entity("MessageBoard", boardName);
  messageBoard.setProperty("count", 0L);
  boardKey = datastore.put(txn, messageBoard);
}
txn.commit();

Come in precedenza, è necessaria una transazione per gestire il caso in cui un altro utente stia tentando di creare o aggiornare un'entità con lo stesso ID stringa. Senza una transazione, se l'entità non esiste e due utenti tentano di crearla, il secondo sovrascrive la prima senza sapere che è successo. Con una transazione, il secondo tentativo non va a buon fine in modo atomico. Se ha senso, l'applicazione può riprovare a recuperare l'entità e aggiornarla.

Quando una transazione non va a buon fine, puoi chiedere all'app di riprovare finché non va a buon fine oppure puoi lasciare che siano gli utenti a gestire l'errore trasmettendolo al livello dell'interfaccia utente dell'app. Non è necessario creare un ciclo di ripetizione per ogni transazione.

Nota: una transazione deve avvenire il più rapidamente possibile per ridurre la probabilità che le entità utilizzate dalla transazione cambino, causando il fallimento della transazione. Per quanto possibile, prepara i dati al di fuori della transazione, quindi esegui la transazione per eseguire operazioni di Datastore che dipendono da uno stato coerente. L'applicazione deve preparare le chiavi per gli oggetti utilizzati al di fuori della transazione, quindi recuperare le entità all'interno della transazione.

Infine, puoi utilizzare una transazione per leggere uno snapshot coerente di Datastore. Questa opzione può essere utile quando sono necessarie più letture per eseguire il rendering di una pagina o esportare dati che devono essere coerenti. Questi tipi di transazioni sono spesso chiamate transazioni di sola lettura, poiché non eseguono scritture. Le transazioni di gruppo singolo di sola lettura non falliscono mai a causa di modifiche contemporaneamente, quindi non è necessario implementare i tentativi di nuovo in caso di errore. Tuttavia, le transazioni tra gruppi possono non riuscire a causa di modifiche contemporanee, pertanto dovrebbero essere previste delle ripetizioni. L'commit e il rollback di una transazione di sola lettura sono entrambi operazioni senza effetti.

DatastoreService ds = DatastoreServiceFactory.getDatastoreService();

// Display information about a message board and its first 10 messages.
Key boardKey = KeyFactory.createKey("MessageBoard", boardName);

Transaction txn = datastore.beginTransaction();

Entity messageBoard = datastore.get(boardKey);
long count = (Long) messageBoard.getProperty("count");

Query q = new Query("Message", boardKey);

// This is an ancestor query.
PreparedQuery pq = datastore.prepare(txn, q);
List<Entity> messages = pq.asList(FetchOptions.Builder.withLimit(10));

txn.commit();

Coda delle attività transazionali

Puoi mettere in coda un'attività nell'ambito di una transazione di Datastore, in modo che venga messa in coda solo (e con garanzia) se la transazione viene eseguita correttamente. Se la transazione viene eseguita, l'attività viene inserita in coda. Una volta inserita in coda, non è garantito che l'attività venga eseguita immediatamente e le eventuali operazioni eseguite all'interno dell'attività vengono eseguite indipendentemente dalla transazione originale. L'attività esegue ripetutamente tentativi finché non riesce. Questo vale per qualsiasi attività in coda nel contesto di una transazione.

Le attività transazionali sono utili perché ti consentono di elencare azioni non di Datastore in una transazione di Datastore (ad esempio l'invio di un'email per confermare un acquisto). Puoi anche associare le azioni di Datastore alla transazione, ad esempio eseguire il commit delle modifiche a gruppi di entità aggiuntivi al di fuori della transazione se e solo se la transazione va a buon fine.

Un'applicazione non può inserire più di cinque attività di transazione nelle code di lavoro durante una singola transazione. Le attività di transazione non devono avere nomi specificati dall'utente.

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
Queue queue = QueueFactory.getDefaultQueue();
Transaction txn = datastore.beginTransaction();
// ...

queue.add(txn, TaskOptions.Builder.withUrl("/path/to/handler"));

// ...

txn.commit();