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
GET <root>/query/Car.findAllPageable?limit=20&offset=0
и вернут следующий JSON:
{
"items": [
{
"id": 1,
"name": "Mazda MX-5",
...
},
... <еще 19 записей> ...
],
"hasMore": true,
"limit": 20,
"offset": 0,
"count": 20,
"links": [
{
"rel": "self",
"href": "{root}/query/Car.findAllPageable"
}
{
"rel": "canonical",
"href": "{root}/query/Car.findAllPageable"
}
{
"rel": "next",
"href": "{root}/query/Car.findAllPageable?offset=20"
}
]
}
Ответ сервера также содержит дополнительную информацию:
- hasMore — true если данная страница не является последней.
- limit — размер страницы используемый сервером.
- offset — используемое смещение.
- count — количество записей на странице.
- ссылка next — URL следующей страницы (если доступна)
- ссылка prev — URL предыдущей страницы (если доступна)
Вторая страница:
{root}/query/Car.findAllPageable?offset=20или
{root]/query/Car.findAllPageable?limit=20&offset=20Третья страница размером 10 записей:
{root}/query/Car.findAllPageable?limit=10&offset=207 записей начиная с третей:
{root}/query/Car.findAllPageable?limit=7&offset=3Сервер всегда использует минимальный limit из укзанного в запросе и используемного в аннотиции. То есть
{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": "<root>/metadata-catalog/entity/Car",
"mediaType": "application/schema+json"
},
{
"rel": "canonical",
"href": "<root>/metadata-catalog/entity/Car",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "{root}/entity/Car"
}
]
}Получить метаданные для класса Car можно вот так:
{root}/metadata-catalog/entity/CarДля запроса Car.findAll так:
{root}/metadata-catalog/query/Car.findAllЕще один способ получения метаданных — вызов OPTIONS метода на базовый URL ресурса.
OPTIONS <root>/entity/BasketСервер вернет ссылку на метаданные в заголовке Link c rel=«describedby»
Link: <root/metadata-catalog/entity/Basket>; rel="describedby"Каталог ресурсов
Каталог ресурсов, как оглавление книги, содержит метаданные для всех доступтых ресурсов. Это правильное место начала работы с незнакомой службой. Здесь всегда можно посмотреть доступные объкты и запросы.
Каталог ресурсов доступен по следующему адресу:
GET <root>/metadata-catalogОтвет сервера:
{
"items": [
{
"name": "Car",
...
},
{
"name": "Car.findAll",
...
},
{
"name": "Car.findAllPageable",
...
}
],
"links": [
{
"rel": "canonical",
"href": "<root>/metadata-catalog"
}
]
}Я урезал ответ сервера исключительно для читабельности. Медаданные для всех ресурсов выглядят также как указано в начале главы.
JSON-схема ресурсов
Хотя JSON схема пока не является утвержденным стандартом и работы над спецификацией еще не закончены, JPS-RS уже частично поддерживает draft 4 спецификации. Это касается формата вывода объектов и списка объектов.
URL метаданных ресурса можно использовать и для получения его (ресурса) JSON схемы. Для этого выполняем HTTP GET запрос используя тип медиа «application/schema+json». То есть установив в HTTP заголовке «accept» значение «application/schema+json».
Получение схемы для класса Car:
GET <root>/metadata-catalog/entity/Car HTTP/1.1
Accept-Encoding: gzip,deflate
accept: application/schema+json
Host: <host:port>
Proxy-Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Ответ сервера:
{
"$schema": "<root>/metadata-catalog/entity/Car#",
"allOf": [
{
"$ref": "rest-schemas/#/singularResource"
}
],
"title": "Car",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string"
},
"shortDescr": {
"type": "string"
},
"longDescr": {
"type": "string"
},
},
"links": [
{
"rel": "describedby",
"href": "<root>/entity/Car"
},
{
"rel": "find",
"href": "{root}/entity/Car/{primaryKey}",
"method": "GET"
},
{
"rel": "create",
"href": "{root}/entity/Car",
"method": "PUT"
},
{
"rel": "update",
"href": "{root}/entity/Car",
"method": "POST"
},
{
"rel": "delete",
"href": "{root}/entity/Car/{primaryKey}",
"method": "DELETE"
}
]
}
На этом все. Надеюсь, вам понравился обзор.
Nightly builds EclipseLink можно скачать здесь:
http://www.eclipse.org/eclipselink/downloads/nightly.phpАвтор: m0mus
