Visão geral da API de armazenamento de dados em Java

O armazenamento de dados do Google App Engine fornece armazenamento dimensionável e robusto de dados para o seu aplicativo da web. O armazenamento de dados é desenvolvido tendo em mente os aplicativos da web, com ênfase no desempenho de leitura e consulta. Ele armazena entidades de dados com propriedades, organizadas de acordo com tipos definidos por aplicativos. Pode executar consultas em entidades do mesmo tipo, com filtros e ordens de classificação em valores e chaves da propriedade. Todas as consultas são pré-indexadas para proporcionar resultados mais rápidos em conjuntos de dados muito grandes. O armazenamento de dados suporta atualizações transacionais, usando agrupamentos de entidade definidos pelo aplicativo como a unidade de transacionalidade na rede de dados distribuída.

• Apresentação do armazenamento de dados
• Interfaces de dados em Java
• Entidades e propriedades
• Consultas e índices
• Transações e grupos de entidades
• Cotas e limites

Apresentação do armazenamento de dados

O armazenamento de dados do Google App Engine armazena e executa consultas sobre objetos de dados conhecidos como entidades. Uma entidade tem uma ou mais propriedades, valores nomeados em um de diversos tipos de dados suportados. Uma propriedade pode ser uma referência a outra entidade.

O armazenamento de dados pode executar diversas operações em uma única transação e reverter a transação inteira em caso de falha de uma das operações. Isso é particularmente útil para os aplicativos de web distribuídos, nos quais diversos usuários podem acessar ou manipular o mesmo objeto de dados ao mesmo tempo.

Diferente dos bancos de dados tradicionais, o armazenamento de dados utiliza uma arquitetura distribuída para gerenciar o dimensionamento para conjuntos de dados muito grandes. Um aplicativo do Google App Engine pode otimizar a distribuição dos dados, descrevendo os relacionamentos entre os objetos de dados e definindo índices para as consultas.

O armazenamento de dados do Google App Engine é bastante consistente, mas não é um banco de dados relacional. Embora a interface do armazenamento de dados tenha diversos recursos similares aos dos bancos de dados tradicionais, suas características exclusivas sugerem uma maneira diferente de projetar e gerenciar os dados, para tirar proveito da capacidade de dimensionamento automático.

Interfaces de dados em Java

As entidades do armazenamento de dados não têm esquema: duas entidades do mesmo tipo não são obrigadas a ter as mesmas propriedades ou usar os mesmos tipos de valores para as mesmas propriedades. O aplicativo é responsável por garantir que as entidades atendam ao esquema quando necessário. O SDK para Java inclui implementações das interfaces JDO (Objetos de dados Java) e JPA (API persistente Java) para dados de modelagem e persistência. Essas interfaces padrão incluem mecanismos para definir classes de objetos de dados e realizar consultas. O armazenamento de dados também oferece uma API de nível inferior, que pode ser usada para implementar outros adaptadores de interface ou apenas usada diretamente nos aplicativos.

Esta documentação descreve a JDO detalhadamente. A maioria das outras fontes de informações sobre a JDO também se aplica ao Google App Engine. Consulte a documentação neste guia pra obter informações sobre diferenças na implementação e recursos não implementados.

A JPA também é suportada. Esta documentação descreve a JPA brevemente. Consulte Como usar a JPA.

A JDO utiliza anotações em classes Java ("plain old Java objects" ou "POJOs") para descrever como as instâncias da classe são armazenadas no armazenamento de dados como entidades, e como as entidades são recriadas como instâncias quando recuperadas do armazenamento de dados. O exemplo abaixo mostra uma classe de dados simples:

Employee.java

import java.util.Date;
import javax.jdo.annotations.IdGeneratorStrategy;
import javax.jdo.annotations.IdentityType;
import javax.jdo.annotations.PersistenceCapable;
import javax.jdo.annotations.Persistent;
import javax.jdo.annotations.PrimaryKey;

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class Employee {
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    private Long id;

    @Persistent
    private String firstName;

    @Persistent
    private String lastName;

    @Persistent
    private Date hireDate;

    public Person(String firstName, String lastName, Date hireDate) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.hireDate = hireDate;
    }

    // Accessors for the fields.  JDO doesn't use these, but your application does.

    public Long getId() {
        return id;
    }

    public String getFirstName() {
        return firstName;
    } 

    // ... other accessors...
}

Você interage com o armazenamento de dados usando um objeto PersistenceManager, obtido a partir de um objeto PersistenceManagerFactory. Como fica caro configurar um PersistenceManagerFactory, certifique-se de obter a instância apenas uma vez durante a existência do seu aplicativo (que pode cobrir muitas solicitações). Uma maneira fácil de fazer isso é inseri-lo em uma única classe, como:

PMF.java

import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManagerFactory;

public final class PMF {
    private static final PersistenceManagerFactory pmfInstance =
        JDOHelper.getPersistenceManagerFactory("transactions-optional");

    private PMF() {}

    public static PersistenceManagerFactory get() {
        return pmfInstance;
    }
}

Você pode instanciar as instâncias das classes de dados e armazená-las no armazenamento de dados:

import java.util.Date;
import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManager;
import javax.jdo.PersistenceManagerFactory;

import Employee;
import PMF;

// ...
        Employee employee = new Employee("Alfred", "Smith", new Date());

        PersistenceManager pm = PMF.get().getPersistenceManager();

        try {
            pm.makePersistent(employee);
        } finally {
            pm.close();
        }

A JDO inclui uma interface de consulta chamada JDOQL. A JDOQL pode ser usada para recuperar entidades como instâncias dessa classe, como mostrado abaixo:

import java.util.List;
import Employee;

// ...
        String query = "select from " + Employee.class.getName() + " where lastName == 'Smith'";
        List<Employee> employees = (List<Employee>) pm.newQuery(query).execute();

Entidades e propriedades

Um objeto de dados do armazenamento de dados do Google App Engine é conhecido como entidade. Uma entidade tem uma ou mais propriedades, valores nomeados em um de diversos tipos de dados, incluindo números inteiros, valores de ponto flutuante, strings, datas, dados binários e muito mais.

Cada entidade também tem uma chave exclusiva que a identifica. A chave mais simples tem um tipo e um ID numérico exclusivo fornecido pelo armazenamento de dados. O ID também pode ser uma string fornecida pelo aplicativo.

Para obter uma entidade do armazenamento de dados, um aplicativo pode utilizar a sua chave ou realizar uma consulta correspondente às propriedades da entidade. Uma consulta pode retornar zero ou mais entidades e os resultados classificados por valores de propriedade. Uma consulta também pode limitar o número de resultados retornados pelo armazenamento de dados, para economizar memória e tempo de execução.

Diferente dos bancos de dados relacionais, o armazenamento de dados do Google App Engine não requer que todas as entidades de um determinado tipo tenham as mesmas propriedades. O aplicativo pode especificar e impor seu modelo de dados usando bibliotecas incluídas com o SDK ou seu próprio código.

Uma propriedade pode ter um ou mais valores. Uma propriedade com diversos valores pode ter valores de tipos mistos. Uma consulta sobre uma propriedade com diversos valores testa se algum desses valores atende aos critérios da consulta. Isso torna essas propriedades úteis para teste de associação.

Consultas e índices

Uma consulta do armazenamento de dados do Google App Engine opera em toda entidade de um determinado tipo (uma classe de dados). Ela especifica zero ou mais filtros nos valores e chaves da propriedade da entidade e zero ou mais ordens de classificação. Uma entidade retorna como um resultado de uma consulta se tiver no mínimo um valor (possivelmente nulo) para cada propriedade mencionada nos filtros e ordens de classificação da consulta, e se todos os critérios do filtro forem atendidos pelos valores da propriedade.

Cada consulta do armazenamento de dados utiliza um índice, uma tabela que contém os resultados da consulta na ordem desejada. Um aplicativo do Google App Engine define seus índices em um arquivo de configuração. O servidor da web para desenvolvimento adiciona sugestões a este arquivo automaticamente, ao encontrar consultas que ainda não têm índices configurados. Você pode ajustar os índices manualmente, editando o arquivo antes de enviar o aplicativo. À medida que o aplicativo faz alterações nas entidades do armazenamento de dados, este atualiza os índices com os resultados corretos. Quando o aplicativo executa uma consulta, o armazenamento de dados obtém os resultados diretamente do índice correspondente.

Esse mecanismo suporta uma ampla variedade de consultas e é adequado para a maioria dos aplicativos. Entretanto, ele não suporta alguns tipos de consultas que você pode ter o costume de fazer em outras tecnologias de banco de dados.

Transações e grupos de entidades

No armazenamento de dados do Google App Engine, qualquer tentativa de criar, atualizar ou excluir uma entidade ocorre em uma transação. Uma transação garante que toda alteração feita na entidade seja salva no armazenamento de dados, ou, no caso de uma falha, nenhuma das alterações seja feita. Isso garante a consistência dos dados em uma entidade.

Você pode executar diversas ações em uma entidade dentro de uma única transação usando a API de transação. Por exemplo, se você quiser incrementar um campo de contador em um objeto. Para fazer isso, você precisa ler o valor do contador, calcular o novo valor e armazená-lo. Sem uma transação, outro processo pode incrementar o contador entre o momento em que você lê o valor e o momento em que você o atualiza, fazendo com que o aplicativo sobrescreva o valor atualizado. A execução da leitura, cálculo e gravação em uma única transação garante que nenhum outro processo interfira na incrementação.

Você pode fazer alterações em diversas entidades dentro de uma única transação. Para suportar isso, o Google App Engine precisa saber com antecedência quais entidades serão atualizadas juntas, para que ele as armazene de uma maneira que possibilite as transações. Ao criar uma entidade, você precisa declarar que uma entidade pertence ao mesmo grupo de entidades que outra entidade. Todas as entidades obtidas, criadas, atualizadas ou excluídas em uma transação devem obrigatoriamente estar no mesmo grupo de entidades.

Grupos de entidades são definidos por uma hierarquia de relacionamentos entre entidades. Para criar uma entidade em um grupo, você declara que a entidade é uma filha de outra entidade já existente no grupo. A outra entidade é o pai. Uma entidade criada sem um pai é uma entidade raiz. Uma entidade raiz sem qualquer filha existe em um grupo de entidades por si só. Cada entidade tem um caminho de relacionamentos pai-filha desde uma entidade raiz até ela mesma (o caminho mais curto é sem a existência de pai). Esse caminho é uma parte essencial da chave completa da entidade. Uma chave completa pode ser representada pelo tipo e ID ou pelo nome da chave de cada entidade no caminho.

O armazenamento de dados usa a concorrência otimista para gerenciar transações. Enquanto uma instância do aplicativo aplica as alterações nas entidades em um grupo de entidades, todas as outras tentativas de atualização de qualquer entidade no grupo falham instantaneamente. O aplicativo pode tentar a transação novamente para aplicá-la aos dados atualizados.

Cotas e limites

Cada chamada para a API do armazenamento de dados conta para a cota de Chamadas da API do armazenamento de dados. Observe que algumas chamadas da biblioteca resultam em diversas chamadas para a API de armazenamento de dados subjacente.

Os dados enviados para o armazenamento de dados pelo aplicativo contam para a cota de Dados enviados para a API (armazenamento de dados). Os dados recebidos pelo aplicativo do armazenamento de dados contam para a cota de Dados recebidos da API (armazenamento de dados).

A quantidade total de dados armazenados atualmente no armazenamento de dados para o aplicativo não pode exceder a cota de Dados armazenados (ajustável). Isso inclui propriedades e chaves da entidade, mas não inclui índices.

A quantidade de tempo de CPU consumida pelas operações do armazenamento de dados se aplica às seguintes cotas:

• Tempo da CPU (ajustável)
• Tempo da CPU do armazenamento de dados

Para obter mais informações sobre cotas, consulte Cotas e a seção "Detalhes da cota" do Console de administração.

Além das cotas, os limites a seguir são aplicados ao uso do armazenamento de dados: