L'API Async Datastore consente di effettuare chiamate parallele non bloccanti al datastore e di recuperare i risultati di queste chiamate in un momento successivo nella gestione della richiesta. Questa documentazione descrive i seguenti aspetti dell'API Async Datastore:
Utilizzo del servizio Async Datastore
Con l'API asincrona del datastore, puoi effettuare chiamate al datastore utilizzando i metodi dell'interfaccia AsyncDatastoreService. Per ottenere questo oggetto, chiama il metodo della classe getAsyncDatastoreService() della classe DatastoreServiceFactory.
import com.google.appengine.api.datastore.AsyncDatastoreService; import com.google.appengine.api.datastore.DatastoreServiceFactory; // ... AsyncDatastoreService datastore = DatastoreServiceFactory.getAsyncDatastoreService();
AsyncDatastoreService
supporta le stesse operazioni di DatastoreService, ad eccezione del fatto che la maggior parte dei metodi restituisce immediatamente un valore Future di cui puoi bloccare il risultato in un secondo momento. Ad esempio, DatastoreService.get() restituisce un'entità, ma AsyncDatastoreService.get() restituisce Future<Entity>
.
// ... Key key = KeyFactory.createKey("Employee", "Max"); // Async call returns immediately Future<Entity> entityFuture = datastore.get(key); // Do other stuff while the get operation runs in the background... // Blocks if the get operation has not finished, otherwise returns instantly Entity entity = entityFuture.get();
Nota:non vengono generate eccezioni finché non chiami il metodo get(). La chiamata a questo metodo consente di verificare che l'operazione asincrona sia riuscita.
Se hai un AsyncDatastoreService
, ma devi eseguire un'operazione in modo sincrono, richiama il metodo AsyncDatastoreService
appropriato e blocca immediatamente il risultato:
// ... Entity entity = new Employee("Employee", "Alfred"); // ... populate entity properties // Make a sync call via the async interface Key key = datastore.put(key).get();
Utilizzo delle transazioni asincrone
Le chiamate API del datastore asincrone possono partecipare alle transazioni proprio come le chiamate sincrone. Ecco una funzione che regola lo stipendio di un Employee
e scrive un'entità SalaryAdjustment
aggiuntiva nello stesso gruppo di entità di Employee
, il tutto all'interno di una singola transazione.
void giveRaise(AsyncDatastoreService datastore, Key employeeKey, long raiseAmount) throws Exception { Future<Transaction> txn = datastore.beginTransaction(); // Async call to lookup the Employee entity Future<Entity> employeeEntityFuture = datastore.get(employeeKey); // Create and put a SalaryAdjustment entity in parallel with the lookup Entity adjustmentEntity = new Entity("SalaryAdjustment", employeeKey); adjustmentEntity.setProperty("adjustment", raiseAmount); adjustmentEntity.setProperty("adjustmentDate", new Date()); datastore.put(adjustmentEntity); // Fetch the result of our lookup to make the salary adjustment Entity employeeEntity = employeeEntityFuture.get(); long salary = (Long) employeeEntity.getProperty("salary"); employeeEntity.setProperty("salary", salary + raiseAmount); // Re-put the Employee entity with the adjusted salary. datastore.put(employeeEntity); txn.get().commit(); // could also call txn.get().commitAsync() here }
Questo esempio illustra un'importante differenza tra le chiamate asincrone senza transazioni e quelle asincrone con transazioni. Se non utilizzi una transazione, l'unico modo per assicurarti che una singola chiamata asincrona sia stata completata è recuperare il valore restituito dall'elemento Future
restituito quando è stata effettuata la chiamata. Quando utilizzi una transazione, la chiamata di Transaction.commit() blocca il risultato di tutte le chiamate asincrone effettuate dall'inizio della transazione prima di eseguirne il commit.
Quindi, nell'esempio precedente, anche se la nostra chiamata asincrona per l'inserimento dell'entità SalaryAdjustment
potrebbe essere ancora in sospeso quando chiamiamo commit()
, il commit non verrà eseguito fino al completamento dell'inserimento. Allo stesso modo, se scegli di chiamare commitAsync()
anziché commit()
, richiama get()
sul Future
restituito da commitAsync()
fino al completamento di tutte le chiamate asincrone in sospeso.
Nota:le transazioni sono associate a un thread specifico, non a un'istanza specifica di DatastoreService
o AsyncDatastoreService
. Ciò significa che se avvii una transazione con un DatastoreService
ed esegui una chiamata asincrona con un AsyncDatastoreService
, la chiamata asincrona partecipa alla transazione. Oppure, per riassumere, DatastoreService.getCurrentTransaction()
e AsyncDatastoreService.getCurrentTransaction()
restituiscono sempre lo stesso Transaction
.
Lavorare con i contratti a termine
Il Javadoc futuro spiega gran parte di ciò che devi sapere per lavorare correttamente con un oggetto Future
restituito dall'API Async Datastore, ma ci sono alcune cose specifiche di App Engine che devi conoscere:
- Quando chiami Future.get(long timeout, TimeUnit unit), il timeout è separato da qualsiasi scadenza RPC impostata al momento della creazione del
AsyncDatastoreService
. Per ulteriori informazioni, consulta Coerenza dei dati nelle query di Cloud Datastore. - Quando chiami Future.cancel(boolean mayInterruptIfRunning) e quella chiamata restituisce
true
, ciò non significa necessariamente che lo stato del tuo datastore sia rimasto invariato. In altre parole, annullare unFuture
non equivale a eseguire il rollback di una transazione.
Query asincrone
Al momento non esponiamo un'API esplicitamente asincrona per le query. Tuttavia, quando richiami PreparedQuery.asIterable(), PreparedQuery.asIterator() o PreparedQuery.asList(FetchOptions fetchOptions), DatastoreService e AsyncDatastoreService restituiscono immediatamente i risultati e precaricano i risultati in modo asincrono. Ciò consente all'applicazione di eseguire operazioni in parallelo durante il recupero dei risultati della query.
// ... Query q1 = new Query("Salesperson"); q1.setFilter(new FilterPredicate("dateOfHire", FilterOperator.LESS_THAN, oneMonthAgo)); // Returns instantly, query is executing in the background. Iterable<Entity> recentHires = datastore.prepare(q1).asIterable(); Query q2 = new Query("Customer"); q2.setFilter(new FilterPredicate("lastContact", FilterOperator.GREATER_THAN, oneYearAgo)); // Also returns instantly, query is executing in the background. Iterable<Entity> needsFollowup = datastore.prepare(q2).asIterable(); schedulePhoneCall(recentHires, needsFollowUp);
Quando utilizzare le chiamate a Datastore asincrone
Le operazioni esposte dall'interfaccia DatastoreService sono sincrone. Ad esempio, quando chiami DatastoreService.get()
, il tuo codice si blocca fino al completamento della chiamata al datastore. Se l'unica cosa che l'applicazione deve fare è visualizzare il risultato di get()
in HTML, è del tutto ragionevole bloccare il completamento della chiamata. Tuttavia, se l'applicazione richiede il risultato di get()
più il risultato di un Query
per visualizzare la risposta e se get()
e Query
non hanno dipendenze dati, attendere il completamento di get()
per avviare Query
è una perdita di tempo. Ecco un esempio di codice che può essere migliorato utilizzando l'API asincrona:
DatastoreService datastore = DatastoreServiceFactory.getDatastoreService(); Key empKey = KeyFactory.createKey("Employee", "Max"); // Read employee data from the Datastore Entity employee = datastore.get(empKey); // Blocking for no good reason! // Fetch payment history Query query = new Query("PaymentHistory"); PreparedQuery pq = datastore.prepare(query); List<Entity> result = pq.asList(FetchOptions.Builder.withLimit(10)); renderHtml(employee, result);
Anziché attendere il completamento di get()
, utilizza un'istanza di AsyncDatastoreService per eseguire la chiamata in modo asincrono:
AsyncDatastoreService datastore = DatastoreServiceFactory.getAsyncDatastoreService(); Key empKey = KeyFactory.createKey("Employee", "Max"); // Read employee data from the Datastore Future<Entity> employeeFuture = datastore.get(empKey); // Returns immediately! // Fetch payment history for the employee Query query = new Query("PaymentHistory", empKey); PreparedQuery pq = datastore.prepare(query); // Run the query while the employee is being fetched List<Entity> result = pq.asList(FetchOptions.Builder.withLimit(10)); // Implicitly performs query asynchronously Entity employee = employeeFuture.get(); // Blocking! renderHtml(employee, result);
Le versioni sincrone e asincrone di questo codice utilizzano quantità simili di CPU (dopo tutto, entrambe svolgono la stessa quantità di lavoro), ma poiché la versione asincrona consente l'esecuzione in parallelo delle due operazioni sul datastore, la versione asincrona ha una latenza minore. In generale, se devi eseguire più operazioni sul datastore che non hanno dipendenze per i dati, AsyncDatastoreService
può migliorare notevolmente la latenza.