Руководство для занятых разработчиков RESTful-сервисов на Java

Прелесть JAX-RS в том, что он почти целиком основан на аннотациях. Это означает, что вы можете превратить практически любой класс в службу RESTful. Вы можете просто превратить POJO в конечную точку REST, добавив к ней аннотации JSR 311. Такие аннотированные POJO называются
классом ресурсов в терминах JAX-RS.

Некоторые из аннотаций JAX-RS находятся на уровне класса, некоторые на уровне метода и другие на уровне параметра метода. Некоторые доступны как на уровне класса, так и на уровне метода. В конечном итоге аннотации объединяются, превращая данный метод Java в конечную точку RESTful, доступную по URL-адресу на основе HTTP. Аннотации должны указывать следующие элементы:

• Относительный путь метода Java — это достигается с помощью аннотации @Path .
• Что такое HTTP-глагол, т.е. какая операция CRUD выполняется — это делается путем указания одной из аннотаций @GET , @PUT , @POST или @DELETE . 
• Тип носителя принят (т.е. формат представления) — аннотация @Consumes .
• Тип возвращаемого носителя — аннотация @Produces .

Два последних являются необязательными. Если опущен, то все типы носителей считаются возможными Давайте рассмотрим простой пример и разберем его:

import javax.ws.rs.*;

@Path("/mail")
@Produces("application/json")
public class EmailService
{
    @POST
    @Path("/new")
    public String sendEmail(@FormParam("subject") String subject,
                            @FormParam("to") String to,
                            @FormParam("body") String body)  {
        return "new email sent";
    }
    
    @GET
    @Path("/new")
    public String getUnread()  {
        return "[]";
    }
   
    @DELETE
    @Path("/{id}")
    public String deleteEmail(@PathParam("id") int emailid)  {
        return "delete " + id;
    }
    
    @GET
    @Path("/export")
    @Produces("text/html")
    public String exportHtml(@QueryParam("searchString") 
                             @DefaultValue("") String search) {
        return "<table><tr>...</tr></table>";
    }
}

Класс определяет интерфейс RESTful для гипотетического почтового сервиса на основе HTTP. Путь верхнего уровня mail относится к корневому пути приложения. Путь к корневому приложению связан с javax.ws.rs.core.Application JAX-RS,   который вы расширяете, чтобы подключить к среде выполнения. Затем мы объявили с аннотацией @Produces, что все методы в этом сервисе создают JSON. Это просто класс по умолчанию, который можно переопределить для отдельных методов, как мы сделали в методе exportHtml . Метод sendMail  определяет типичный HTTP-пост, содержимое которого отправляется в виде HTML-формы. Намерение здесь будет состоять в публикации на http://myserver.com/mail/newформа для нового электронного письма, которое должно быть отправлено. Как видите, API позволяет связывать каждое отдельное поле формы с параметром метода. Обратите внимание, что у вас есть другой метод для того же пути.

Если вы выполните HTTP get в  / mail / new , вместо этого будет вызван метод Java с аннотацией @GET . Предположительно семантика get / mail / new будет заключаться в получении списка непрочитанных писем. Далее, обратите внимание , как путь deleteEmail метода parametarized целочисленным идентификатором электронной почты для удаления. Фигурные скобки указывают, что «id» на самом деле является параметром. Значение этого параметра привязано к тому, что  помечено @PathParam («id») . Таким образом, если мы удалим HTTP на http://myserver.com/mail/453, мы будем вызывать метод deleteEmail с аргументом emailid = 453. Наконец, exportHtmlМетод демонстрирует, как мы можем получить указатель на параметры запроса. Когда вы аннотируете параметр с помощью @QueryParam («x»), значение берется из параметра HTTP-запроса с именем x. @DefaultValue аннотации обеспечивают по умолчанию в случае, если параметр запроса отсутствует. Так, вызов http://myserver.org/mail/export?searchString=RESTful будет вызывать exportHtml метод с поиском параметра = «успокоительный».

Чтобы предоставить этот сервис, сначала нам нужно написать реализацию  javax.ws.rs.core.Application. Это всего лишь несколько строк:

public class MyRestApp extends javax.ws.rs.core.Application {
   public Set>Class> getClasses() {
      HashSet S = new HashSet();
      S.add(EmailService.class);
      return S;
   }
}

Как это будет подключено к вашему серверу, зависит от вашей реализации JAX-RS. Прежде чем мы покинем API, я должен упомянуть, что это еще не все. У вас есть доступ к объектам Request и Response. У вас есть аннотации для доступа к другой контекстной информации и метаданным, таким как заголовки HTTP, файлы cookie и т. Д. И вы можете обеспечить настраиваемую сериализацию и десериализацию между типами мультимедиа и объектами Java.