Пакет com.google.appengine.api.datastore

Хранилище данных предоставляет возможность постоянного хранения для приложений App Engine, которое можно использовать напрямую или через интерфейсы JDO или JPA.

См.:
Описание

Краткое описание интерфейсов

DatastoreConfig	Настраиваемые свойства хранилища данных.
DatastoreService	Интерфейс DatastoreService предоставляет доступ к системе хранилище данных без схемы.
PreparedQuery	Содержит метод для получения и возврата объектов из Query.
Transaction	Описывает логический блок операций с хранилищем данных.

Краткий обзор классов

Blob	Blob содержит байтовый массив неограниченного размера.
DatastoreServiceFactory	Создает реализации DatastoreService.
DataTypeTranslator	DataTypeTranslator представляет собой обслуживающий класс для преобразования буфера протокола хранилища данных Property и классов, доступных пользователям (String, User и т. д.).
DataTypeTranslator.ComparableByteArray	Оболочка для массива byte[], который реализует класс Comparable.
DataTypeUtils	DataTypeUtils представляет простой интерфейс, который позволяет в коде пользователя определить, какие классы можно безопасно сохранить в качестве свойств в хранилище данных.
Entity	Объект Entity является основной рабочей единицей хранилища данных.
EntityTranslator	Класс EntityTranslator содержит логику, которая позволяет перевести объект Entity в буферы протокола, используемые для его передачи в конкретную реализацию API.
FetchOptions	Описывает ограничение, сдвиг и размер части данных, которые нужно применить при выполнении интерфейса PreparedQuery.
FetchOptions.Builder	Содержит статические методы создания для класса FetchOptions.
Key	Первичный ключ объекта хранилища данных.
KeyFactory	Позволяет создавать произвольные объекты Key в группе корневых объектов (без родителя).
KeyFactory.Builder	Вспомогательный класс, который помогает создавать объекты Keys с предками.
Link	Экземпляр класса Link представляет собой URL ограниченной длины.
Query	Query содержит запрос на ноль или более объектов Entity из хранилища данных.
Query.FilterPredicate	FilterPredicate представляет собой контейнер данных, предназначенный для хранения предиката одного фильтра.
Query.SortPredicate	SortPredicate представляет собой контейнер данных, предназначенный для хранения предиката одного порядка сортировки.
ShortBlob	ShortBlob содержит байтовый массив, не превышающий DataTypeUtils.MAX_SHORT_BLOB_PROPERTY_LENGTH.
Text	Text создает оболочку вокруг строки неограниченного размера.

Краткое описание перечислимых типов

ImplicitTransactionManagementPolicy	Описывает различные правила, которым должно следовать хранилище данных при подразумеваемом управлении транзакциями.
Query.FilterOperator	С помощью FilterOperator можно указать тип операции, которую нужно применить к фильтру.
Query.SortDirection	SortDirection позволяет управлять порядком сортировки.

Краткое описание исключений

DatastoreFailureException	Исключение DatastoreFailureException вызывается в случае возникновения неизвестной ошибки при обращении к хранилищу данных.
DatastoreNeedIndexException	Исключение DatastoreNeedIndexException вызывается в случае, если для запроса, требующего наличия индекса, найти нужный индекс не удается.
DatastoreTimeoutException	Исключение DatastoreTimeoutException вызывается при возникновении таймаута операции с хранилищем данных.
EntityNotFoundException	Исключение EntityNotFoundException вызывается, если не удается найти объект Entity с указанным ключом Key.
PreparedQuery.TooManyResultsException	Указывает количество результатов, найденных для PreparedQuery.asSingleEntity().

Описание пакета com.google.appengine.api.datastore

Хранилище данных предоставляет возможность постоянного хранения для приложений App Engine, которое можно использовать напрямую или через интерфейсы JDO или JPA. Он предоставляет резервное хранения для отказоустойчивости. Дополнительная информация доступна в документации.

Пакет содержит низкоуровневый API для хранилища данных, который предназначен преимущественно для разработчиков инфраструктур. Разработчики приложений могут воспользоваться предоставленными интерфейсами JDO или JPA к хранилищу данных. При использовании API хранилища данных распространенный образец использования следующий:

 // Get a handle on the datastore itself
 DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

 // Lookup data by known key name
 Entity userEntity = datastore.get(KeyFactory.createKey("UserInfo", email));

 // Or perform a query
 Query query = new Query("Task", userEntity);
 query.addFilter("dueDate", Query.FilterOperator.LESS_THAN, today);
 for (Entity taskEntity : datastore.prepare(query).asIterable()) {
   if ("done".equals(taskEntity.getProperty("status"))) {
     datastore.delete(taskEntity);
   } else {
     taskEntity.setProperty("status", "overdue");
     datastore.put(taskEntity);
   }
 }
 

Вот ряд основных моментов:

• К действующему хранилищу данных доступ осуществляется с помощью объекта DatastoreService, который получается из класса DatastoreServiceFactory.
• Единица хранения представлена объектом Entity именованного типа (в данном случае "UserInfo" и "Task").
• У объектов есть значение Key, которое создается из класса KeyFactory, чтобы получить определенный объект. Если ключ не определен полностью, объекты Query можно использовать, чтобы получить один объект Entity, несколько объектов в виде списка Interable или Iterator или количество подходящих объектов.
• У объектов есть именованные свойства, значения которых могут быть базовых типов или коллекций из базовых типов. Конечно, более сложные сериализуемые объекты можно сохранить в виде байтовых массивов. Однако это может отрицательно сказаться на эффективности запросов по этим свойствам.
• Объекты могут быть связаны со структурой дерева. Объект Query в приведенном выше фрагменте осуществляет поиск только объектов Task, связанных с определенным объектом UserInfo, а затем фильтрует Tasks, отображая только задачи, которые должны были быть выполнены до сегодня.

На практике для всех нетривиальных запросов требуется индекс, что позволяет удостовериться в эффективной обработке индивидуальных запросов. Набор индексов, необходимых для приложения, можно указать в файле WEB-INF/datastore-indexes.xml, или они будут автоматически созданы при тестировании приложения на сервере разработки. Если для запроса требуется несуществующий индекс, во время выполнения вызывается исключение DatastoreNeedIndexException.

Несмотря на то что Google App Engine позволяет создавать несколько версий приложения, для всех них существует только одно хранилище данных, которое совместно используется всеми версиями. Аналогично, всеми версиями совместно используется и набор индексов.