Como criar e usar chaves de entidade

Cada entidade no Cloud Datastore tem uma chave que a identifica de maneira exclusiva. A chave consiste nos seguintes componentes:

  • O namespace da entidade, que permite a multilocação
  • O tipo da entidade, que a categoriza para as consultas do Cloud Datastore
  • Um caminho ancestral opcional, que localiza a entidade na hierarquia do Cloud Datastore
  • Um identificador da entidade individual, que pode ser:

    • uma string de nome da chave;
    • um código numérico inteiro

Como o identificador é parte da chave da entidade, ele é associado permanentemente à entidade e não pode ser alterado. Atribua o identificador de uma dessas maneiras:

  • Especifique sua própria string de nome de chave para a entidade.
  • Deixe o Cloud Datastore atribuir automaticamente um código numérico inteiro à entidade.

Como especificar um nome de chave para uma entidade

Para atribuir um nome de chave a uma entidade, forneça o nome como o segundo argumento para o construtor quando criar a entidade:

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

Para que o Cloud Datastore atribua um código numérico automaticamente, omita esse argumento:

Entity employee = new Entity("Employee");

Como atribuir identificadores

Você pode configurar o Cloud Datastore para gerar códigos automáticos usando duas políticas de identificação automática diferentes:

  • A política default gera uma sequência aleatória de códigos não utilizados que são distribuídos uniformemente de forma aproximada. Cada código pode ter até 16 dígitos decimais.
  • A política legacy cria uma sequência de códigos inteiros menores não consecutivos.

Se você quiser exibir os códigos de entidade para o usuário e/ou depender da ordem deles, a melhor coisa a fazer é usar a alocação manual.

Como usar caminhos ancestrais

As entidades no Cloud Datastore formam um espaço hierarquicamente estruturado, semelhante à estrutura de diretórios de um sistema de arquivos. Ao criar uma entidade, é possível designar outra entidade como pai e a nova é a entidade filho (observe que, diferentemente do que ocorre em um sistema de arquivos, a entidade pai não precisa existir de verdade). Uma entidade sem pai é uma entidade raiz. A associação entre uma entidade e a entidade pai é permanente e não pode ser alterada depois que a entidade é criada. O Cloud Datastore nunca atribuirá o mesmo código numérico a duas entidades com o mesmo pai ou a duas entidades raiz (sem pai).

O pai de uma entidade, o pai do pai, e assim por diante são ancestrais dela. O filho, o filho do filho, e assim por diante são descendentes dela. Uma entidade raiz e todos os descendentes pertencem ao mesmo grupo de entidades. A sequência de entidades começando com uma entidade raiz e procedendo de pai para filho, levando a uma determinada entidade, constitui o caminho ancestral dessa entidade. A chave completa que identifica a entidade consiste em uma sequência de pares de identificadores de tipo que especifica seu caminho ancestral e termina com os da própria entidade:

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

Para uma entidade raiz, o caminho ancestral está vazio, e a chave consiste unicamente no próprio tipo e identificador da entidade:

[Person:GreatGrandpa]

Este conceito é ilustrado pelo seguinte diagrama:

Mostra o relacionamento da entidade raiz com entidades filho no grupo de entidades

Para designar o pai de uma entidade, informe a chave da entidade pai como argumento do construtor Entity() ao criar a entidade filho. Para receber a chave, chame o método getKey() da entidade pai:

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

Se a nova entidade também tiver um nome de chave, forneça esse nome como o segundo argumento do construtor Entity() e a chave da entidade pai como o terceiro argumento:

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

Como gerar chaves

Os aplicativos podem usar a classe KeyFactory e criar um objeto Key para uma entidade a partir de componentes conhecidos, como o tipo e o identificador da entidade. No caso de uma entidade sem pai, transmita o tipo e o identificador (que podem ser uma string de nome de chave ou um código numérico) ao método estático KeyFactory.createKey() para criar a chave. Os exemplos a seguir criam uma chave para uma entidade Person de tipo com o nome da chave "GreatGrandpa" ou código numérico 74219:

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

Se a chave incluir um componente de caminho, use a classe auxiliar KeyFactory.Builder para criar o caminho. Com o método addChild dessa classe, uma única entidade é adicionada ao caminho e o próprio criador é retornado. Assim, é possível encadear uma série de chamadas, começando com a entidade raiz, para criar o caminho com uma entidade por vez. Depois de criar o caminho completo, chame getKey para recuperar a chave 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();

A classe KeyFactory também inclui os métodos estáticos keyToString e stringToKey para conversão entre chaves e as respectivas representações de string:

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

A representação de string de uma chave é "segura para Web": não contém caracteres considerados especiais em HTML nem em URLs.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Java 8