Изучаем Java EE 7 - [247]
>@Path("/customer")
>public class CustomerRestService {
>··@Inject
>··private CustomerEJB customerEJB;
>··@Path("{customerId}")
>··public Customer getCustomer(@PathParam("customerId") Long customerId) {
>····if (customerId < 1000)
>······throw new IllegalArgumentException("Id must be greater than 1000!");
>····Customer customer = customerEJB.find(customerId);
>····if (customer == null)
>······throw new WebApplicationException(Response.Status.NOT_FOUND);
>····return customer;
>··}
>}
Чтобы держать код сухим[3], можно предоставить специальные поставщики отображения исключений. Такой поставщик отображает общее исключение на Response. Если будет сгенерировано такое исключение, то реализация JAX-RS отловит его и вызовет соответствующий поставщик отображения исключений. Поставщик отображения исключений является реализацией ExceptionMapper
>@Provider
>public class EntityNotFoundMapper implements ExceptionMapper
>··public Response toResponse(javax.persistence.EntityNotFoundException ex) {
>····return Response.status(404). entity(ex.getMessage()). type(MediaType.TEXT_PLAIN). build();
>··}
>}
Жизненный цикл и обратные вызовы
При поступлении запроса происходит разрешение той REST-службы, которой он был адресован, и создается новый экземпляр соответствующего класса. Соответственно, жизненный цикл такой службы является «позапросным»; служба может игнорировать проблемы, связанные с параллелизмом, и безопасно пользоваться переменными экземпляров.
При развертывании в контейнере Java EE (сервлетном или EJB) классы ресурсов и поставщики JAX-RS также могут использовать описанные в JSR 250 технологию управления жизненным циклом и аннотации безопасности: @PostConstruct, @PreDestroy, @RunAs, @RolesAllowed, @PermitAll, @DenyAll и @DeclareRoles. Жизненный цикл ресурса может использовать аннотации @PostConstruct и @PreDestroy для добавления бизнес-логики уже после создания ресурса или перед его удалением. На рис. 15.3 показан жизненный цикл, свойственный большинству компонентов платформы Java EE.
Рис. 15.3. Жизненный цикл ресурса
Упаковка
Веб-службы в стиле REST могут упаковываться в файлы WAR-архивов или EJB JAR-архивов в зависимости от того, готовите вы службу для веб-профиля или полномасштабную службу для Java EE 7. Не забывайте, что веб-служба в стиле REST также может сопровождаться аннотациями @Stateless или @Singleton — в таком случае с ней можно будет использовать службы сеансовых компонентов. У веб-служб SOAP было несколько сгенерированных артефактов для упаковки, но с REST складывается иная ситуация. Разработчик отвечает лишь за упаковку классов, аннотированных @Path (и других вспомогательных классов). Обратите внимание: в JAX-RS 2.0 отсутствует дескриптор развертывания.
Вызов веб-служб в стиле REST
Итак, вы уже научились писать веб-службы с передачей состояния представления, которые могут обрабатывать данные, выполнять в базе данных операции из разряда CRUD, доставлять информацию с сервера и т. д. Как получить к ним доступ? Как следует из рис. 15.1, для этого нужно просто сделать HTTP-запрос к URI. Воспользуйтесь любым инструментом, обеспечивающим такую возможность, и свободно вызывайте любые описанные выше службы в стиле REST.
Первый мыслимый инструмент такого рода — любой браузер. Откройте браузер, введите URI в адресную строку — и получите визуальное представление. К сожалению, браузеры работают только с HTTP-методами GET и POST. Если вы хотите добиться от браузера большего, к нему вполне можно подключить несколько модулей. Такие подключаемые модули поддерживают работу с методами PUT и DELETE (в качестве примера можно привести Postman из Chrome). Еще один очень функциональный инструмент, которым можно воспользоваться, — cUrl. Этот инструмент командной строки обеспечивает доступ к деталям HTTP-протокола и, в частности, позволяет вызывать веб-службы REST.
До выхода JAX-RS 2.0 в Java отсутствовал стандартный способ простого вызова веб-служб в стиле REST. Приходилось либо полагаться на низкоуровневый API java.net.HttpURLConnection, либо пользоваться проприетарным API того или иного фреймворка (например, Jersey, Resteasy или Restlet). JAX-RS ликвидирует этот пробел с помощью своего текучего, легкого в использовании API для выстраивания запросов.
Клиентский API
В JAX-RS 2.0 появился новый клиентский API, с помощью которого можно с легкостью делать HTTP-запросы к удаленным REST-службам (несмотря на все низкоуровневые функции протокола HTTP). Речь идет о текучем API для построения запросов (использующем шаблон проектирования «Построитель»), в котором задействуется небольшое количество классов и интерфейсов (обзор пакета javax.ws.rs.client представлен в табл. 15.8, а информация об API Response приводилась в табл. 15.6). Очень часто вам придется сталкиваться с тремя основными классами: Client, WebTarget и Response. Интерфейс Client (получаемый с помощью ClientBuilder) — это построитель интерфейсов WebTarget. Интерфейс WebTarget представляет самостоятельный URI, с которого вы можете инициировать запросы для получения Response. На основании этого ответа можно проверять HTTP-состояние, длину или cookie. Но гораздо важнее, что вы можете получать содержимое ответа. Это делается с помощью класса Entity.
