Cómo crear y usar claves de entidad

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

  • El espacio de nombres de la entidad, que permite la función multiusuario.
  • El tipo de entidad, que la clasifica con el propósito de realizar consultas de Cloud Datastore.
  • Una ruta principal opcional que ubica la entidad dentro de la jerarquía de Cloud Datastore.
  • Un identificador para la entidad individual, que puede ser

    • una string de nombre de clave
    • un ID numérico de enteros

Debido a que es parte de la clave de la entidad, el identificador se encuentra asociado de forma permanente a la entidad y no se puede cambiar. El identificador se puede asignar de las siguientes dos maneras:

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

Cómo especificar un nombre de clave para una entidad

Cuando asignes un nombre de clave a la entidad, proporciona el nombre como el segundo argumento para el constructor cuando crees la entidad:

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

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

Entity employee = new Entity("Employee");

Cómo asignar identificadores

Puedes configurar Cloud Datastore para generar ID automáticos mediante dos políticas de ID automático distintas:

  • La política default genera una secuencia aleatoria de ID sin usar con una distribución aproximadamente uniforme. Cada ID puede tener hasta 16 dígitos decimales.
  • La política legacy crea una secuencia de ID no consecutivos más breves compuestos por números enteros.

Si deseas mostrar los ID de las entidades a los usuarios o depender de que estos los soliciten, lo más recomendable es que uses la asignación manual.

Cómo usar las rutas principales

Las entidades de Cloud Datastore conforman un espacio con estructura jerárquica similar a la estructura de directorios de un sistema de archivos. Cuando creas una entidad, tienes la opción de designar otra entidad como principal, en cuyo caso la entidad nueva sería secundaria de la entidad principal (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, no es necesario que la entidad principal exista realmente). Las entidades que no tienen una entidad principal se denominan entidades raíz. La asociación entre una entidad y su entidad principal es permanente y no se puede cambiar una vez que se crea la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades con la misma entidad principal o a dos entidades raíz (que no tengan una principal).

La entidad principal de una entidad, la entidad superior a su principal, y así sucesivamente, son sus entidades principales. Las entidades secundarias, las secundarias de sus secundarias, y así sucesivamente, son sus descendientes. Una entidad raíz y todas sus descendientes pertenecen al mismo grupo de entidades. La secuencia de entidades que comienza con una entidad raíz y sigue de superior a secundario, hasta llegar a determinada entidad, constituye la ruta principal de esa entidad. La clave completa que identifica a una entidad consta de una secuencia de pares de tipo identificador que especifican su ruta principal y que finaliza con los de la entidad misma:

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

Para una entidad raíz, la ruta principal está vacía y la clave consta solo del tipo y del identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el diagrama siguiente:

Grupo de entidad

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

Java 8

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

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

Java 7

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

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

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

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

Cómo generar claves

Las aplicaciones pueden usar la clase KeyFactory con el fin de crear un objeto Key para una entidad a partir de componentes conocidos, como el identificador y el tipo de entidad. Para una entidad sin superior, pasa el tipo y el identificador (ya sea un ID numérico o una string de nombre de clave) al método estático KeyFactory.createKey() para crear la clave. Los ejemplos siguientes crean una clave para una entidad del tipo Person con nombre de clave "GreatGrandpa" o 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 auxiliar KeyFactory.Builder para compilar la ruta. Este método de clase addChild agrega una sola entidad a la ruta y muestra el compilador para que puedas encadenar una serie de llamadas, comenzando con la entidad raíz, y así crear la ruta de una entidad a la vez. Después de compilar toda la ruta, llama a getKey para recuperar la clave resultante:

Java 8

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

Java 7

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 la conversión entre claves y sus representaciones de strings:

Java 8

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);

Java 7

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

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno estándar de App Engine para Java 8