Crear y usar claves de entidad

Cada entidad de Datastore tiene una clave que la identifica de forma única. La clave consta de los siguientes componentes:

  • El espacio de nombres de la entidad, que permite la arquitectura multicliente
  • El tipo de la entidad, que la clasifica para las consultas de Datastore
  • Una ruta de ancestro opcional que indica la ubicación de la entidad en la jerarquía de Datastore.

  • Un identificador de la entidad individual, que puede ser

    • Una cadena key name
    • un ID numérico entero

Como el identificador forma parte de la clave de la entidad, se asocia permanentemente a la entidad y no se puede cambiar. Puedes asignar el identificador de dos formas:

  • Especifica tu propia cadena de nombre de clave para la entidad.
  • Permite que Datastore asigne automáticamente a la entidad un ID numérico entero.

Especificar el nombre de una clave de una entidad

Para asignar un nombre de clave a una entidad, proporciona el nombre como segundo argumento al constructor cuando crees la entidad:

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

Para que Datastore asigne un ID numérico automáticamente, omite este argumento:

Entity employee = new Entity("Employee");

Asignar identificadores

Puede configurar Datastore para que genere IDs automáticos mediante dos políticas de IDs automáticos diferentes:

  • La política default genera una secuencia aleatoria de IDs no utilizados que se distribuyen de forma aproximadamente uniforme. Cada ID puede tener hasta 16 dígitos decimales.
  • La política legacy crea una secuencia de IDs de números enteros más pequeños no consecutivos.

Si quieres mostrar los IDs de entidad al usuario o depender de su orden, lo mejor es usar la asignación manual.

Usar rutas de ancestro

Las entidades de Cloud Datastore forman un espacio estructurado jerárquicamente similar a la estructura de directorios de un sistema de archivos. Cuando creas una entidad, puedes designar otra entidad como principal. La nueva entidad será una secundaria de la entidad principal (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, la entidad principal no tiene por qué existir). Una entidad sin elemento superior es una entidad raíz. La asociación entre una entidad y su elemento superior es permanente y no se puede cambiar una vez que se ha creado la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades con el mismo elemento superior ni a dos entidades raíz (aquellas que no tienen un elemento superior).

El elemento superior de una entidad, el elemento superior del elemento superior, etc., son sus ancestros. Sus elementos secundarios, los elementos secundarios de los elementos secundarios, etc., son sus descendientes. Una entidad raíz y todos sus descendientes pertenecen al mismo grupo de entidades. La secuencia de entidades que empieza con una entidad raíz y continúa de la entidad superior a la secundaria hasta llegar a una entidad determinada constituye la ruta de ancestros de esa entidad. La clave completa que identifica la entidad consta de una secuencia de pares tipo-identificador que especifican su ruta de ancestros y termina con los de la propia entidad:

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

En el caso de una entidad raíz, la ruta de ancestro está vacía y la clave se compone únicamente del tipo y el identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el siguiente diagrama:

Muestra la relación de la entidad raíz con las entidades secundarias del grupo de entidades.

Para designar el elemento superior de una entidad, proporciona la clave de la entidad superior como argumento del constructor Entity() al crear la entidad secundaria. Para obtener la clave, llama al método getKey() de la entidad principal:

Entity employee = new Entity("Employee");
datastore.put(employee);

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

Si la nueva entidad también tiene un nombre de clave, proporciona el nombre de la clave como segundo argumento al constructor Entity() y la clave de la entidad principal como tercer argumento:

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

Generar claves

Las aplicaciones pueden usar la clase KeyFactory para crear un objeto Key de una entidad a partir de componentes conocidos, como el tipo y el identificador de la entidad. En el caso de una entidad sin elemento superior, pasa el tipo y el identificador (una cadena de nombre de clave o un ID numérico) al método estático KeyFactory.createKey() para crear la clave. En los siguientes ejemplos se crea una clave para una entidad de tipo Person con el nombre de clave "GreatGrandpa" o el ID numérico 74219:

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

Si la clave incluye un componente de ruta, puedes usar la clase de ayuda KeyFactory.Builder para crear la ruta. El método addChild de esta clase añade una sola entidad a la ruta y devuelve el propio compilador, por lo que puedes encadenar una serie de llamadas, empezando por la entidad raíz, para crear la ruta de una entidad a la vez. Después de crear la ruta completa, llama a getKey para obtener la clave resultante:

Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

La clase KeyFactory también incluye los métodos estáticos keyToString y stringToKey para convertir entre claves y sus representaciones de cadena:

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 representación de cadena de una clave es "segura para la Web": no contiene caracteres que se consideren especiales en HTML o en URLs.