Creazione e utilizzo delle chiavi di entità

Ogni entità in Datastore ha una chiave che la identifica in modo univoco. La chiave è costituita dai seguenti componenti:

  • Lo spazio dei nomi dell'entità, che consente la multitenancy.
  • Il tipo di entità, che lo classifica ai fini delle query Datastore
  • Un percorso predecessore facoltativo che individua l'entità all'interno della gerarchia di Datastore.

  • Un identificatore per la singola entità, che può essere

    • una stringa nome chiave
    • un ID numerico intero

Poiché fa parte della chiave dell'entità, è associato definitivamente all'entità e non può essere modificato. Puoi assegnare l'identificatore in due modi:

  • Specifica la tua stringa nome chiave per l'entità.
  • Lascia che Datastore assegni automaticamente all'entità un ID numerico intero.

Specifica di un nome chiave per un'entità

Per assegnare un nome a una chiave a un'entità, fornisci il nome come secondo argomento al costruttore quando crei l'entità:

Entity employee = new Entity("Employee", "asalieri");

Per consentire a Datastore di assegnare automaticamente un ID numerico, ometti questo argomento:

Entity employee = new Entity("Employee");

Assegnazione degli identificatori

Puoi configurare Datastore per generare ID automatici utilizzando due diversi criteri di ID automatico:

  • Il criterio default genera una sequenza casuale di ID non utilizzati che sono distribuiti casualmente. Ogni ID può contenere fino a 16 cifre decimali.
  • Il criterio legacy crea una sequenza di ID interi più piccoli non consecutivi.

Se vuoi mostrare gli ID entità all'utente e/o dipende dal suo ordine, la cosa migliore da fare è utilizzare l'allocazione manuale.

Utilizzo dei percorsi predecessori

Le entità in Cloud Datastore formano uno spazio strutturato in modo gerarchico simile alla directory di un file system. Quando crei un'entità, puoi facoltativamente designare un'altra entità come principale; la nuova entità è un secondario dell'entità principale (tieni presente che, a differenza di un file system, l'entità principale non deve esistere effettivamente). Un'entità senza entità padre è un'entità root. L'associazione tra un'entità e la relativa entità è permanente e non può essere modificata una volta creata l'entità. Cloud Datastore non assegnerà mai lo stesso ID numerico a due entità con lo stesso padre o a due entità radice (quelle senza un padre).

Il genitore di un'entità, il genitore e così via sono i suoi antenati, i suoi figli, i loro figli, ecc. Un'entità radice e tutti i relativi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che iniziano con un'entità radice e procedono da un'entità padre all'altra, generando un'entità specifica, costituendo il percorso dell'antenato. La chiave completa che identifica l'entità è costituita da una sequenza di coppie tipo-identificatore che specificano il percorso del predecessore e terminano con quelle dell'entità stessa:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Per un'entità radice, il percorso del predecessore è vuoto e la chiave è composta esclusivamente dal tipo e dall'identificatore dell'entità:

[Person:GreatGrandpa]

Questo concetto è illustrato dal seguente diagramma:

Mostra la relazione dell'entità radice con le entità secondarie nel gruppo di entità

Per designare l'entità padre, fornisci la chiave dell'entità padre come argomento al costruttore Entity() durante la creazione dell'entità secondaria. Puoi ottenere la chiave chiamando il metodo getKey() dell'entità principale:

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

Se la nuova entità ha anche un nome di chiave, fornisci il nome della chiave come secondo argomento del costruttore Entity() e la chiave dell'entità padre come terzo argomento:

Entity address = new Entity("Address", "addr1", employee.getKey());

Generazione di chiavi

Le applicazioni possono utilizzare la classe KeyFactory per creare un oggetto Key per un'entità da componenti noti, come il tipo e l'identificatore dell'entità. Per un'entità senza principale, trasmetti il tipo e l'identificatore (una stringa del nome della chiave o un ID numerico) al metodo statico KeyFactory.createKey() per creare la chiave. I seguenti esempi creano una chiave per un'entità di tipo Person con nome della chiave "GreatGrandpa" o ID numerico 74219:

Key k1 = KeyFactory.createKey("Person", "GreatGrandpa");
Key k2 = KeyFactory.createKey("Person", 74219);

Se la chiave include un componente del percorso, puoi utilizzare la classe helper KeyFactory.Builder per crearlo. Questo metodo di classe addChild di questa classe aggiunge una singola entità al percorso e restituisce il generatore stesso, in modo da poter concatenare una serie di chiamate, a partire dall'entità radice, per creare il percorso di un'entità alla volta. Dopo aver creato il percorso completo, richiama getKey per recuperare la chiave risultante:

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

La classe KeyFactory include anche i metodi statici keyToString e stringToKey per la conversione tra chiavi e relative rappresentazioni delle stringhe:

appengine-java8/datastore/src/test/java/com/example/appengine/EntitiesTest.java 
String personKeyStr = KeyFactory.keyToString(k);

// Some time later (for example, after using personKeyStr in a link).
Key personKey = KeyFactory.stringToKey(personKeyStr);
Entity person = datastore.get(personKey);

La rappresentazione della stringa di una chiave è "web-safe": non contiene caratteri considerati speciali in HTML o negli URL.