Краткий обзор новых возможностей JPA-RS в EclipseLink
EclipseLink — это ORM фрэймворк с открытым исходным кодом, разрабатываемый Eclipse Foundation. В конце года запланирован выход версии 2.6.0. проекта. В преддверии этого, я хочу ознакомить вас с некоторыми новыми возможностями службы JPA-RS, которая является частью EclipseLink.JPA-RS позволяет автоматически генерировать RESTful сервисы на базе предоставленной пользователем JPA модели. При этом практически никакой дополнительной работы от пользователя не требуется.Версия сервиса в URLОт версии к версии возможно изменение семантики протокола передачи данных. JSON-cхема ресурсов в версии 2.0 сервиса отличается от JSON-схемы, используемой в предыдущей версии. Для обеспечения совместимости JPA-RS умеет возвращать данные используя старые форматы. Для этого версия протокола вынесена в URL.Базовый URL выглядит так:
http (s)://{server: port}/{app}/persistence/{version}/{persistent-unit}/… Где: server: port — адрес и порт сервера. app — имя вашего приложения (context root). persistence — Точка входа в JPA-RS приложение. Константа. version — Не обязательный. Версия JPA-RS. На данный момент поддерживаются значения «v1.0» (предыдущая версия), «v2.0» (новая версия) и «latest» (последняя версия). persistent-unit — Имя persistent unit как указано в persistence.xml. Версия сервиса может быть пропущена, в этом случае используется значение «v1.0».Примеры:
Запрос объекта Car с примарным ключом 1 из персистент юнита car-pu используя семантику протокола версии 1.0:
http (s)://localhost:8080/jpars-test/persistence/car-pu/entity/Car/1 Тоже самое: http (s)://localhost:8080/jpars-test/persistence/v1.0/car-pu/entity/Car/1 Запрос тех же данных, но используя семантику сервиса версии 2.0: http (s)://localhost:8080/jpars-test/persistence/v2.0/car-pu/entity/Car/1 Так как последняя версия на данный момент 2.0, то следующий запрос вернет тоже самое, что и предыдущий: http (s)://localhost:8080/jpars-test/persistence/latest/car-pu/entity/Car/1 Далее, исключительно для читабельности, я обозначу http (s)://localhost:8080/jpars-test/persistence/v2.0 как {root}.Постраничный вывод JPARS позволяет разделять на страницы длинные списки и возвращать только выбранную пользователем страницу. Это работает для запросов (Named Query) и для полей типа Collection.Постраничный вывод — это единственная функция JPA-RS, требующая конфигурации. Это делается с помощью аннотаций.Рассмотрим следующий пример:
@Entity @Table (name = «CAR») @NamedQueries ({ @NamedQuery ( name = «Car.findAll», query = «SELECT c FROM Car c ORDER BY c.name»), @NamedQuery ( name = «Car.findAllPageable», query = «SELECT c FROM Car c ORDER BY c.name»), }) @RestPageableQueries ({ @RestPageableQuery (queryName = «Car.findAllPageable», limit = 20) }) public class Car { @Id @Column (name = «CAR_ID») private Integer id;
@Column (name = «CAR_NAME») private String name; @Column (name = «CAR_SHORT_DESCR») private String shortDescr;
@Column (name = «CAR_LONG_DESCR») private String longDescr; // Getters and setters are skipped } Это стандартный entity класс c двумя JPARS аннотациями.
@RestPageableQueries ({
@RestPageableQuery (queryName = «Car.findAllPageable», limit = 20)
})
Этот кусок кода говорит, что запрос Car.findAllPageable должен выдаваться через RESTful сервис постранично с размером страницы — 20 записей.Для конфигурации постраничного вывода при вызове используются два параметра: limit — размер страницы. Не может быть выше значения limit указанного в аннотации @RestPageableQuery. Оно же является значением по умолчанию.
offset — смещение от начала списка. Порядковый номер первой возвращаемой записи. Значение по умолчению — 0.
К примеру, следующие запросы аналогичны:
GET
{root}/query/Car.findAllPageable? limit=100 вернет только 20 записей. При этом значение limit в ответе сервера будет 20, как в примере выше.Фильтрация полей При запросе данных иногда бывает нужно вернуть не всю запись, а только некоторые поля. К примеру, поле longDescr класса Car содержит текст внушительного размера, который мы не хотим передавать по сети. Именно для этого служит фильтрация полей.Фильтрация конфигурируется двумя параметрами:
fields — список полей, возвращаемых сервером. Поля разделяются запятыми. excludeFields — список полей, которые не возвращаются сервером. К примеру: GET {root}/entity/Car/1? fields=id, name, shortDescr Вернет только поля ud, name и shortDescr класса Car: { «id»: 1, «name»: «Mazda MX-5», «shortDescr»: «двухместный родстер», … } Тоже самое вернет и следующий запрос: GET {root}/entity/Car/1? excludeFields=longDescr При попытке использовать оба параметра fields и excludeFields в одном запросе, сервер вернет ошибку.Метаданные Метаданные содержат дополнительную информацию о ресурсе. В нашем слусае это ссылка на JSON схему ресурса и базовый URL.К примеру, метаданные для нашего класса Car выглядят так:
{
«name»: «Car»,
«links»: [
{
«rel»: «alternate»,
«href»:»
GET
Получение схемы для класса Car:
GET
На этом все. Надеюсь, вам понравился обзор. Nightly builds EclipseLink можно скачать здесь: http://www.eclipse.org/eclipselink/downloads/nightly.php
